add Typescript defs and improve documentation (launchdarkly#3)

.circleci/config.yml

@@ -12,12 +12,14 @@ node-template: &node-template
     - checkout
     - run: echo "Node version:" `node --version`
     - run: npm install
+    - run: npm run lint
     - run:
         command: npm test
         environment:
           JEST_JUNIT_OUTPUT: "reports/junit/js-test-results.xml"
     - store_test_results:
         path: reports/junit
+    - run: npm run check-typescript
     - store_artifacts:
         path: reports/junit
 

.eslintignore

@@ -0,0 +1 @@
+node_modules/

.gitignore

@@ -1,4 +1,4 @@
 node_modules
 package-lock.json
 junit.xml
-
+test-types.js

CHANGELOG.md

@@ -2,10 +2,10 @@
 
 All notable changes to the LaunchDarkly Node.js SDK DynamoDB integration will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
-## [1.0.0] - 2018-11-15
-
-Initial release.
-
 ## [1.1.0] - 2018-11-20
 ### Added:
 - it is now possible to specify a prefix string for the database keys, so that multiple SDK clients can share the same DynamoDB table without interfering with each other's data as long as they use different prefixes.
+
+## [1.0.0] - 2018-11-15
+
+Initial release.

README.md

@@ -13,37 +13,37 @@ Quick setup
 
 This assumes that you have already installed the LaunchDarkly Node.js SDK.
 
-1. Install this package with `npm`:
+1. In DynamoDB, create a table which has the following schema: a partition key called "namespace" and a sort key called "key", both with a string type. The LaunchDarkly library does not create the table automatically, because it has no way of knowing what additional properties (such as permissions and throughput) you would want it to have.
+
+2. Install this package with `npm`:
 
         npm install ldclient-node-dynamodb-store --save
 
-2. Require the package:
+3. Require the package:
 
         var DynamoDBFeatureStore = require('ldclient-node-dynamodb-store');
 
-3. When configuring your SDK client, add the DynamoDB feature store:
+4. When configuring your SDK client, add the DynamoDB feature store:
 
         var store = DynamoDBFeatureStore('YOUR TABLE NAME');
         var config = { featureStore: store };
         var client = LaunchDarkly.init('YOUR SDK KEY', config);
 
-The specified table must already exist in DynamoDB. It must have a partition key called "namespace" and a sort key called "key".
-
-By default, the DynamoDB client will try to get your AWS credentials and region name from environment variables and/or local configuration files, as described in the AWS SDK documentation. You can also specify any valid [DynamoDB client options](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#constructor-property) like this:
+    By default, the DynamoDB client will try to get your AWS credentials and region name from environment variables and/or local configuration files, as described in the AWS SDK documentation. You can also specify any valid [DynamoDB client options](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html#constructor-property) like this:
 
         var dynamoDBOptions = { accessKeyId: 'YOUR KEY', secretAccessKey: 'YOUR SECRET' };
         var store = DynamoDBFeatureStore('YOUR TABLE NAME', { clientOptions: dynamoDBOptions });
 
-Alternatively, if you already have a fully configured DynamoDB client object, you can tell LaunchDarkly to use that:
+    Alternatively, if you already have a fully configured DynamoDB client object, you can tell LaunchDarkly to use that:
 
         var store = DynamoDBFeatureStore('YOUR TABLE NAME', { dynamoDBClient: myDynamoDBClientInstance });
 
-4. If you are running a [LaunchDarkly Relay Proxy](https://github.com/launchdarkly/ld-relay) instance, or any other process that will prepopulate the DynamoDB table with feature flags from LaunchDarkly, you can use [daemon mode](https://github.com/launchdarkly/ld-relay#daemon-mode), so that the SDK retrieves flag data only from DynamoDB and does not communicate directly with LaunchDarkly. This is controlled by the SDK's `useLdd` option:
+5. If you are running a [LaunchDarkly Relay Proxy](https://github.com/launchdarkly/ld-relay) instance, or any other process that will prepopulate the DynamoDB table with feature flags from LaunchDarkly, you can use [daemon mode](https://github.com/launchdarkly/ld-relay#daemon-mode), so that the SDK retrieves flag data only from DynamoDB and does not communicate directly with LaunchDarkly. This is controlled by the SDK's `useLdd` option:
 
         var config = { featureStore: store, useLdd: true };
         var client = LaunchDarkly.init('YOUR SDK KEY', config);
 
-5. If the same DynamoDB table is being shared by SDK clients for different LaunchDarkly environments, set the `prefix` option to a different short string for each one to keep the keys from colliding:
+6. If the same DynamoDB table is being shared by SDK clients for different LaunchDarkly environments, set the `prefix` option to a different short string for each one to keep the keys from colliding:
 
         var store = DynamoDBFeatureStore('YOUR TABLE NAME', { prefix: 'env1' });
 
@@ -55,7 +55,7 @@ To reduce traffic to DynamoDB, there is an optional in-memory cache that retains
         var store = DynamoDBFeatureStore('YOUR TABLE NAME', { cacheTTL: 0 });
 
 About LaunchDarkly
------------
+------------------
 
 * LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard.  With LaunchDarkly, you can:
     * Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
@@ -69,6 +69,7 @@ About LaunchDarkly
     * [Python](http://docs.launchdarkly.com/docs/python-sdk-reference "LaunchDarkly Python SDK")
     * [Go](http://docs.launchdarkly.com/docs/go-sdk-reference "LaunchDarkly Go SDK")
     * [Node.JS](http://docs.launchdarkly.com/docs/node-sdk-reference "LaunchDarkly Node SDK")
+    * [Electron](http://docs.launchdarkly.com/docs/electron-sdk-reference "LaunchDarkly Electron SDK")
     * [.NET](http://docs.launchdarkly.com/docs/dotnet-sdk-reference "LaunchDarkly .Net SDK")
     * [Ruby](http://docs.launchdarkly.com/docs/ruby-sdk-reference "LaunchDarkly Ruby SDK")
     * [iOS](http://docs.launchdarkly.com/docs/ios-sdk-reference "LaunchDarkly iOS SDK")

dynamodb_feature_store.js

@@ -1,5 +1,4 @@
 var AWS = require('aws-sdk');
-var dataKind = require('ldclient-node/versioned_data_kind');
 var winston = require('winston');
 
 var helpers = require('./dynamodb_helpers');

index.d.ts

@@ -0,0 +1,63 @@
+// Type definitions for ldclient-node-dynamodb-store
+
+/**
+ * Interface for the DynamoDB feature store component to be used with the LaunchDarkly SDK.
+ *
+ * See: https://docs.launchdarkly.com/v2.0/docs/using-a-persistent-feature-store
+ */
+
+declare module 'ldclient-node-dynamodb-store' {
+  import { LDFeatureStore, LDLogger } from 'ldclient-node';
+  import { DynamoDB } from 'aws-sdk';
+
+  /**
+   * Create a feature flag store backed by DynamoDB.
+   */
+  export function DynamoDBFeatureStore(
+    /**
+     * The table name in DynamoDB. This table must already exist (see readme).
+     */
+    tableName: string,
+
+    /**
+     * Options for configuring the feature store.
+     */
+    options?: LDDynamoDBOptions
+  ): LDFeatureStore;
+
+  /**
+   * Options for configuring a DynamoDBFeatureStore.
+   */
+  export interface LDDynamoDBOptions {
+    /**
+     * Options to be passed to the DynamoDB client constructor, as defined by the AWS SDK.
+     */
+    clientOptions?: DynamoDB.DocumentClient.DocumentClientOptions & DynamoDB.Types.ClientConfiguration;
+
+    /**
+     * Specifies an existing, already-configured DynamoDB client instance that the feature store
+     * should use rather than creating one of its own. If you specify an existing client, then the
+     * clientOptions property is ignored.
+     */
+    dynamoDBClient?: DynamoDB.DocumentClient;
+
+    /**
+     * An optional namespace prefix for all keys stored in DynamoDB. Use this if you are sharing
+     * the same database table between multiple clients that are for different LaunchDarkly
+     * environments, to avoid key collisions. 
+     */
+    prefix?: string;
+
+    /**
+     * The expiration time for local caching, in seconds. To disable local caching, set this to zero.
+     * If not specified, the default is 15 seconds.
+     */
+    cacheTTL?: number;
+
+    /**
+     * A logger to be used for warnings and errors generated by the feature store. If not specified,
+     * the default is an instance of winston.Logger.
+     */
+    logger?: LDLogger;
+  }
+}

package.json

@@ -5,16 +5,21 @@
   "main": "dynamodb_feature_store.js",
   "license": "Apache-2.0",
   "scripts": {
-    "test": "jest --ci --forceExit"
+    "test": "jest --ci --forceExit",
+    "check-typescript": "node_modules/typescript/bin/tsc",
+    "lint": "eslint --format 'node_modules/eslint-formatter-pretty' --ignore-path .eslintignore ."
   },
+  "types": "./index.d.ts",
   "devDependencies": {
     "babel-core": "6.26.0",
     "babel-jest": "22.4.3",
     "babel-preset-env": "1.6.1",
     "eslint": "5.8.0",
+    "eslint-formatter-pretty": "1.3.0",
     "jest": "23.6.0",
     "jest-junit": "5.2.0",
-    "ldclient-node": ">= 5.7.0"
+    "ldclient-node": ">= 5.7.0",
+    "typescript": "3.0.1"
   },
   "jest": {
     "rootDir": ".",

test-types.ts

@@ -0,0 +1,3 @@
+
+// This file exists only so that we can run the TypeScript compiler in the CI build
+// to validate our index.d.ts file.

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "strict": true,
+    "lib": [
+      "es6"
+    ]
+  },
+  "files": [
+    "index.d.ts",
+    "test-types.ts"
+  ]
+}