@hyphen/sdk 1.2.0 → 1.3.0

package/README.md

@@ -17,6 +17,7 @@ The Hyphen Node.js SDK is a JavaScript library that allows developers to easily
 	- [Toggle API](#toggle-api)
 	- [Toggle Hooks](#toggle-hooks)
 	- [Toggle Error Handling](#toggle-error-handling)
+	- [Toggle Caching](#toggle-caching)
 	- [Toggle Self-Hosted](#toggle-self-hosted)
 - [Contributing](#contributing)
 - [Testing Your Changes](#testing-your-changes)
@@ -167,32 +168,32 @@ console.log('Boolean toggle value:', result); // true
 | *applicationId* | `string` | The application ID for your Hyphen project. You can find this in the Hyphen dashboard. |
 | *environment?* | `string` | The environment for your Hyphen project such as `production`. Default uses `process.env.NODE_ENV`  |
 | *context?* | `ToggleContext` | The context object that contains the user and custom attributes. This is optional. |
-| *cache?* | `{ ttl: number}` | Whether to use the cache or not. |
+| *caching?* | `{ ttl: number, generateCacheKeyFn: (context?: ToggleContext) => string}` | Whether to use the cache or not and a function to set the key. The `ttl` is in seconds |
 
 ## Toggle API
 
 | Method | Parameters | Description |
 |----------------|----------------|----------------|
 | *setContext* | `context: ToggleContext` | Set the context for the toggle. This is optional. |
-| *get<Type>* | `key: string, defaultValue: T, options?: ToggleRequestOptions` | Get the value of a toggle. This is a generic method that can be used to get any type from toggle. |
-| *getBoolean* | `key: string, defaultValue: boolean, options?: ToggleRequestOptions` | Get the value of a boolean toggle. |
-| *getNumber* | `key: string, defaultValue: number, options?: ToggleRequestOptions` | Get the value of a number toggle. |
-| *getString* | `key: string, defaultValue: string, options?: ToggleRequestOptions` | Get the value of a string toggle. |
-| *getObject<Type>* | `key: string, defaultValue: any, options?: ToggleRequestOptions` | Get the value of a object toggle. |
+| *get<Type>* | `key: string, defaultValue: T, options?: ToggleGetOptions` | Get the value of a toggle. This is a generic method that can be used to get any type from toggle. |
+| *getBoolean* | `key: string, defaultValue: boolean, options?: ToggleGetOptions` | Get the value of a boolean toggle. |
+| *getNumber* | `key: string, defaultValue: number, options?: ToggleGetOptions` | Get the value of a number toggle. |
+| *getString* | `key: string, defaultValue: string, options?: ToggleGetOptions` | Get the value of a string toggle. |
+| *getObject<Type>* | `key: string, defaultValue: any, options?: ToggleGetOptions` | Get the value of a object toggle. |
 
 ## Toggle Hooks
 
 The following hooks are available for Toggle:
 | Hook | object | Description |
 |----------------|----------------|----------------|
-| *beforeGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleRequestOptions }` | Called before the boolean toggle is fetched. |
-| *afterGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleRequestOptions, result: boolean }` | Called after the boolean toggle is fetched. |
-| *beforeGetNumber* | `{ key: string, defaultValue:number, options?: ToggleRequestOptions }` | Called before the number toggle is fetched. |
-| *afterGetNumber* | `{ key: string, defaultValue:number, options?: ToggleRequestOptions, result: number }` | Called after the number toggle is fetched. |
-| *beforeGetString* | `{ key: string, defaultValue:string, options?: ToggleRequestOptions }` | Called before the string toggle is fetched. |
-| *afterGetString* | `{ key: string, defaultValue:string, options?: ToggleRequestOptions, result: string }` | Called after the string toggle is fetched. |
-| *beforeGetObject* | `{ key: string, defaultValue:any, options?: ToggleRequestOptions }` | Called before the object toggle is fetched. |
-| *afterGetObject* | `{ key: string, defaultValue:any, options?: ToggleRequestOptions, result: any }` | Called after the object toggle is fetched. |
+| *beforeGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleGetOptions }` | Called before the boolean toggle is fetched. |
+| *afterGetBoolean* | `{ key: string, defaultValue:boolean, options?: ToggleGetOptions, result: boolean }` | Called after the boolean toggle is fetched. |
+| *beforeGetNumber* | `{ key: string, defaultValue:number, options?: ToggleGetOptions }` | Called before the number toggle is fetched. |
+| *afterGetNumber* | `{ key: string, defaultValue:number, options?: ToggleGetOptions, result: number }` | Called after the number toggle is fetched. |
+| *beforeGetString* | `{ key: string, defaultValue:string, options?: ToggleGetOptions }` | Called before the string toggle is fetched. |
+| *afterGetString* | `{ key: string, defaultValue:string, options?: ToggleGetOptions, result: string }` | Called after the string toggle is fetched. |
+| *beforeGetObject* | `{ key: string, defaultValue:any, options?: ToggleGetOptions }` | Called before the object toggle is fetched. |
+| *afterGetObject* | `{ key: string, defaultValue:any, options?: ToggleGetOptions, result: any }` | Called after the object toggle is fetched. |
 
 You can use the hooks to modify the request or the response. For example, you can use the `beforeGetBoolean` hook to log the request before it is sent to the server.
 
@@ -311,6 +312,89 @@ try {
 }
 ```
 
+## Toggle Caching
+The SDK supports caching of toggle values to improve performance and reduce the number of requests made to the server. You can enable caching by providing a `caching` option in the constructor.
+
+```javascript
+import { Toggle, ToggleContext } from '@hyphen/sdk';
+
+const context: ToggleContext = {
+	targetingKey: 'user-123',
+	ipAddress: '203.0.113.42',
+	customAttributes: {
+		subscriptionLevel: 'premium',
+		region: 'us-east',
+	},
+	user: {
+		id: 'user-123',
+		email: 'john.doe@example.com',
+		name: 'John Doe',
+		customAttributes: {
+			role: 'admin',
+		},
+	},
+};
+
+const toggleOptions = {
+  publicApiKey: 'your_public_api_key',
+  applicationId: 'your_application_id',
+  context: context,
+  uris: [
+	'https://your-self-hosted-horizon-url',
+  ],
+  caching: {
+	ttl: 60, // Cache for 60 seconds
+};
+
+const toggle = new Toggle(toggleOptions);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
+If you want to use a custom cache key generation function, you can provide a `generateCacheKeyFn` function in the `caching` option:
+
+```javascript
+import { Toggle, ToggleContext } from '@hyphen/sdk';
+
+const context: ToggleContext = {
+	targetingKey: 'user-123',
+	ipAddress: '203.0.113.42',
+	customAttributes: {
+		subscriptionLevel: 'premium',
+		region: 'us-east',
+	},
+	user: {
+		id: 'user-123',
+		email: 'john.doe@example.com',
+		name: 'John Doe',
+		customAttributes: {
+			role: 'admin',
+		},
+	},
+};
+
+const toggleOptions = {
+  publicApiKey: 'your_public_api_key',
+  applicationId: 'your_application_id',
+  context: context,
+  uris: [
+	'https://your-self-hosted-horizon-url',
+  ],
+  caching: {
+	ttl: 60, // Cache for 60 seconds
+	generateCacheKeyFn: (context) => {
+		return `toggle-${context?.targetingKey || 'default'}-hyphen-sdk-boolean`;
+	},
+  },
+};
+
+const toggle = new Toggle(toggleOptions);
+
+const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
+console.log('Boolean toggle value:', result); // true
+```
+
 ## Toggle Self-Hosted
 
 Toggle uses [Horizon](https://hyphen.ai/horizon) to fetch the feature flags. If you are using a self-hosted version of Hyphen you can use the `uris` option in the constructor to set the url of your self-hosted version:

package/dist/index.cjs

@@ -63,6 +63,7 @@ var Toggle = class extends import_hookified.Hookified {
   _context;
   _throwErrors = false;
   _uris;
+  _caching;
   /*
    * Create a new Toggle instance. This will create a new client and set the options.
    * @param {ToggleOptions}
@@ -75,6 +76,7 @@ var Toggle = class extends import_hookified.Hookified {
     this._context = options.context;
     this._throwErrors = options.throwErrors ?? false;
     this._uris = options.uris;
+    this._caching = options.caching;
   }
   /**
   * Get the application ID
@@ -161,11 +163,25 @@ var Toggle = class extends import_hookified.Hookified {
     this._uris = value;
   }
   /**
+  * Get the caching options.
+  * @returns {ToggleCachingOptions | undefined}
+  */
+  get caching() {
+    return this._caching;
+  }
+  /**
+  * Set the caching options.
+  * @param {ToggleCachingOptions | undefined} value
+  */
+  set caching(value) {
+    this._caching = value;
+  }
+  /**
   * This is a helper function to set the public API key. It will check if the key starts with public_ and set it. If it
-  * does set it will also set the client to undefined to force a new one to be created. If it does not, 
+  * does set it will also set the client to undefined to force a new one to be created. If it does not,
   * it will emit an error and console warning and not set the key. Used by the constructor and publicApiKey setter.
-  * @param key 
-  * @returns 
+  * @param key
+  * @returns
   */
   setPublicApiKey(key) {
     if (!key.startsWith("public_")) {
@@ -197,7 +213,8 @@ var Toggle = class extends import_hookified.Hookified {
       const options = {
         application: this._applicationId,
         environment: this._environment,
-        horizonUrls: this._uris
+        horizonUrls: this._uris,
+        cache: this._caching
       };
       await import_server_sdk.OpenFeature.setProviderAndWait(new import_openfeature_server_provider.HyphenProvider(this._publicApiKey, options));
       this._client = import_server_sdk.OpenFeature.getClient(this._context);

package/dist/index.d.cts

@@ -12,6 +12,10 @@ declare enum ToggleHooks {
     beforeGetObject = "beforeGetObject",
     afterGetObject = "afterGetObject"
 }
+type ToggleCachingOptions = {
+    ttl?: number;
+    generateCacheKeyFn?: (context?: ToggleContext) => string;
+};
 type ToggleOptions = {
     /**
      * Your application name
@@ -34,13 +38,11 @@ type ToggleOptions = {
      * @type {ToggleContext}
      */
     context?: ToggleContext;
-    caching?: {
-        /**
-         * The time in seconds to cache the feature flag values
-         * @type {number} - this is in milliseconds
-         */
-        ttl?: number;
-    };
+    /**
+     * Cache options to use for the request
+     * @type {ToggleCachingOptions}
+     */
+    caching?: ToggleCachingOptions;
     /**
      * Throw errors in addition to emitting them
      * @type {boolean}
@@ -55,7 +57,7 @@ type ToggleOptions = {
      */
     uris?: string[];
 };
-type ToggleRequestOptions = {
+type ToggleGetOptions = {
     /**
      * The context to use for evaluating feature flags
      * @type {ToggleContext}
@@ -69,7 +71,8 @@ declare class Toggle extends Hookified {
     private _client;
     private _context;
     private _throwErrors;
-    private _uris?;
+    private _uris;
+    private _caching;
     constructor(options: ToggleOptions);
     /**
      * Get the application ID
@@ -131,6 +134,16 @@ declare class Toggle extends Hookified {
      * @param {Array<string>} value
      */
     set uris(value: string[] | undefined);
+    /**
+     * Get the caching options.
+     * @returns {ToggleCachingOptions | undefined}
+     */
+    get caching(): ToggleCachingOptions | undefined;
+    /**
+     * Set the caching options.
+     * @param {ToggleCachingOptions | undefined} value
+     */
+    set caching(value: ToggleCachingOptions | undefined);
     /**
      * This is a helper function to set the public API key. It will check if the key starts with public_ and set it. If it
      * does set it will also set the client to undefined to force a new one to be created. If it does not,
@@ -159,7 +172,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<T>}
      */
-    get<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    get<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
     /**
      * Get a boolean value from the feature flag. This will check the type of the default value and call the
      * appropriate function. It will also set the context if it is not set.
@@ -168,7 +181,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<boolean>} - The value of the feature flag
      */
-    getBoolean(key: string, defaultValue: boolean, options?: ToggleRequestOptions): Promise<boolean>;
+    getBoolean(key: string, defaultValue: boolean, options?: ToggleGetOptions): Promise<boolean>;
     /**
      * Get a string value from the feature flag.
      * @param {string} key - The key of the feature flag
@@ -176,8 +189,8 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<string>} - The value of the feature flag
      */
-    getString(key: string, defaultValue: string, options?: ToggleRequestOptions): Promise<string>;
-    getNumber(key: string, defaultValue: number, options?: ToggleRequestOptions): Promise<number>;
+    getString(key: string, defaultValue: string, options?: ToggleGetOptions): Promise<string>;
+    getNumber(key: string, defaultValue: number, options?: ToggleGetOptions): Promise<number>;
     /**
      * Get an object value from the feature flag. This will check the type of the default value and call the
      * appropriate function. It will also set the context if it is not set.
@@ -186,7 +199,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<T>} - The value of the feature flag
      */
-    getObject<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    getObject<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
 }
 
-export { Toggle, type ToggleContext, ToggleHooks, type ToggleOptions, type ToggleRequestOptions };
+export { Toggle, type ToggleCachingOptions, type ToggleContext, type ToggleGetOptions, ToggleHooks, type ToggleOptions };

package/dist/index.d.ts

@@ -12,6 +12,10 @@ declare enum ToggleHooks {
     beforeGetObject = "beforeGetObject",
     afterGetObject = "afterGetObject"
 }
+type ToggleCachingOptions = {
+    ttl?: number;
+    generateCacheKeyFn?: (context?: ToggleContext) => string;
+};
 type ToggleOptions = {
     /**
      * Your application name
@@ -34,13 +38,11 @@ type ToggleOptions = {
      * @type {ToggleContext}
      */
     context?: ToggleContext;
-    caching?: {
-        /**
-         * The time in seconds to cache the feature flag values
-         * @type {number} - this is in milliseconds
-         */
-        ttl?: number;
-    };
+    /**
+     * Cache options to use for the request
+     * @type {ToggleCachingOptions}
+     */
+    caching?: ToggleCachingOptions;
     /**
      * Throw errors in addition to emitting them
      * @type {boolean}
@@ -55,7 +57,7 @@ type ToggleOptions = {
      */
     uris?: string[];
 };
-type ToggleRequestOptions = {
+type ToggleGetOptions = {
     /**
      * The context to use for evaluating feature flags
      * @type {ToggleContext}
@@ -69,7 +71,8 @@ declare class Toggle extends Hookified {
     private _client;
     private _context;
     private _throwErrors;
-    private _uris?;
+    private _uris;
+    private _caching;
     constructor(options: ToggleOptions);
     /**
      * Get the application ID
@@ -131,6 +134,16 @@ declare class Toggle extends Hookified {
      * @param {Array<string>} value
      */
     set uris(value: string[] | undefined);
+    /**
+     * Get the caching options.
+     * @returns {ToggleCachingOptions | undefined}
+     */
+    get caching(): ToggleCachingOptions | undefined;
+    /**
+     * Set the caching options.
+     * @param {ToggleCachingOptions | undefined} value
+     */
+    set caching(value: ToggleCachingOptions | undefined);
     /**
      * This is a helper function to set the public API key. It will check if the key starts with public_ and set it. If it
      * does set it will also set the client to undefined to force a new one to be created. If it does not,
@@ -159,7 +172,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<T>}
      */
-    get<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    get<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
     /**
      * Get a boolean value from the feature flag. This will check the type of the default value and call the
      * appropriate function. It will also set the context if it is not set.
@@ -168,7 +181,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<boolean>} - The value of the feature flag
      */
-    getBoolean(key: string, defaultValue: boolean, options?: ToggleRequestOptions): Promise<boolean>;
+    getBoolean(key: string, defaultValue: boolean, options?: ToggleGetOptions): Promise<boolean>;
     /**
      * Get a string value from the feature flag.
      * @param {string} key - The key of the feature flag
@@ -176,8 +189,8 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<string>} - The value of the feature flag
      */
-    getString(key: string, defaultValue: string, options?: ToggleRequestOptions): Promise<string>;
-    getNumber(key: string, defaultValue: number, options?: ToggleRequestOptions): Promise<number>;
+    getString(key: string, defaultValue: string, options?: ToggleGetOptions): Promise<string>;
+    getNumber(key: string, defaultValue: number, options?: ToggleGetOptions): Promise<number>;
     /**
      * Get an object value from the feature flag. This will check the type of the default value and call the
      * appropriate function. It will also set the context if it is not set.
@@ -186,7 +199,7 @@ declare class Toggle extends Hookified {
      * @param {ToggleRequestOptions} options - The options to use for the request. This can be used to override the context.
      * @returns {Promise<T>} - The value of the feature flag
      */
-    getObject<T>(key: string, defaultValue: T, options?: ToggleRequestOptions): Promise<T>;
+    getObject<T>(key: string, defaultValue: T, options?: ToggleGetOptions): Promise<T>;
 }
 
-export { Toggle, type ToggleContext, ToggleHooks, type ToggleOptions, type ToggleRequestOptions };
+export { Toggle, type ToggleCachingOptions, type ToggleContext, type ToggleGetOptions, ToggleHooks, type ToggleOptions };

package/dist/index.js

@@ -28,6 +28,7 @@ var Toggle = class extends Hookified {
   _context;
   _throwErrors = false;
   _uris;
+  _caching;
   /*
    * Create a new Toggle instance. This will create a new client and set the options.
    * @param {ToggleOptions}
@@ -40,6 +41,7 @@ var Toggle = class extends Hookified {
     this._context = options.context;
     this._throwErrors = options.throwErrors ?? false;
     this._uris = options.uris;
+    this._caching = options.caching;
   }
   /**
   * Get the application ID
@@ -126,11 +128,25 @@ var Toggle = class extends Hookified {
     this._uris = value;
   }
   /**
+  * Get the caching options.
+  * @returns {ToggleCachingOptions | undefined}
+  */
+  get caching() {
+    return this._caching;
+  }
+  /**
+  * Set the caching options.
+  * @param {ToggleCachingOptions | undefined} value
+  */
+  set caching(value) {
+    this._caching = value;
+  }
+  /**
   * This is a helper function to set the public API key. It will check if the key starts with public_ and set it. If it
-  * does set it will also set the client to undefined to force a new one to be created. If it does not, 
+  * does set it will also set the client to undefined to force a new one to be created. If it does not,
   * it will emit an error and console warning and not set the key. Used by the constructor and publicApiKey setter.
-  * @param key 
-  * @returns 
+  * @param key
+  * @returns
   */
   setPublicApiKey(key) {
     if (!key.startsWith("public_")) {
@@ -162,7 +178,8 @@ var Toggle = class extends Hookified {
       const options = {
         application: this._applicationId,
         environment: this._environment,
-        horizonUrls: this._uris
+        horizonUrls: this._uris,
+        cache: this._caching
       };
       await OpenFeature.setProviderAndWait(new HyphenProvider(this._publicApiKey, options));
       this._client = OpenFeature.getClient(this._context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphen/sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Hyphen SDK for Node.js",
   "type": "module",
   "main": "dist/index.cjs",
@@ -29,15 +29,15 @@
   "author": "Team Hyphen <hello@hyphen.ai>",
   "license": "MIT",
   "devDependencies": {
-    "@swc/core": "^1.11.24",
-    "@types/node": "^22.15.17",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@swc/core": "^1.11.29",
+    "@types/node": "^22.15.21",
+    "@vitest/coverage-v8": "^3.1.4",
     "rimraf": "^6.0.1",
     "tsd": "^0.32.0",
-    "tsup": "^8.4.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3",
-    "xo": "^0.60.0"
+    "vitest": "^3.1.4",
+    "xo": "^1.0.0"
   },
   "files": [
     "dist",