Skip to content

Commit

Permalink
Update JS SDK docs (Catnip) (#338)
Browse files Browse the repository at this point in the history 
* Update JS SDK docs (Catnip)
  • Loading branch information
@adams85
adams85 authored Nov 28, 2023
1 parent bcd33c3 commit 7320474
Show file tree
Hide file tree
Showing 4 changed files with 241 additions and 67 deletions.
80 changes: 63 additions & 17 deletions website/docs/sdk-reference/js-ssr.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -236,8 +236,8 @@ The `details` result contains the following information:
| `isDefaultValue` | `boolean` | True when the default value passed to `getValueDetailsAsync()` is returned due to an error. |
| `errorMessage` | `string` | In case of an error, this field contains the error message. |
| `errorException` | `any` | In case of an error, this field contains the related exception object (if any). |
| `matchedEvaluationRule` | `RolloutRule` | If the evaluation was based on a targeting rule, this field contains that specific rule. |
| `matchedEvaluationPercentageRule` | `RolloutPercentageItem` | If the evaluation was based on a percentage rule, this field contains that specific rule. |
| `matchedTargetingRule` | `ITargetingRule` | The targeting rule (if any) that matched during the evaluation and was used to return the evaluated value. |
| `matchedPercentageOption` | `IPercentageOption` | The percentage option (if any) that was used to select the evaluated value. |
| `fetchTime` | `Date` | The last download time (UTC) of the current config. |

## User Object
Expand All @@ -254,12 +254,12 @@ let userObject = new configcat.User('#UNIQUE-USER-IDENTIFIER#');
let userObject = new configcat.User('[email protected]');
```

| Parameters | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | **REQUIRED.** Unique identifier of a user in your application. Can be any `string` value, even an email address. |
| `email` | Optional parameter for easier targeting rule definitions. |
| `country` | Optional parameter for easier targeting rule definitions. |
| `custom` | Optional `dictionary of strings` representing the custom attributes of a user for advanced targeting rule definitions. e.g. User role, Subscription type. |
| Parameters | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | **REQUIRED.** Unique identifier of a user in your application. Can be any `string` value, even an email address. |
| `email` | Optional parameter for easier targeting rule definitions. |
| `country` | Optional parameter for easier targeting rule definitions. |
| `custom` | Optional dictionary for custom attributes of a user for advanced targeting rule definitions. E.g. User role, Subscription type. |

For advanced targeting:

Expand All @@ -275,6 +275,46 @@ let userObject = new configcat.User(
);
```

The `custom` dictionary also allows attribute values other than `string` values:

```js
let userObject = new configcat.User("#UNIQUE-USER-IDENTIFIER#");
userObject.custom = {
Rating: 4.5,
RegisteredAt: new Date("2023-11-22T12:34:56.000Z"),
Roles: ["Role1", "Role2"]
};
```

### User Object Attribute Types

All comparators support `string` values as User Object attribute (in some cases they need to be provided in a specific format though, see below),
but some of them also support other types of values. It depends on the comparator how the values will be handled. The following rules apply:

**Text-based comparators** (EQUALS, IS ONE OF, etc.)
* accept `string` values,
* all other values are automatically converted to `string` (a warning will be logged but evaluation will continue as normal).

**SemVer-based comparators** (IS ONE OF, <, >=, etc.)
* accept `string` values containing a properly formatted, valid semver value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**Number-based comparators** (=, <, >=, etc.)
* accept `number` values,
* accept `string` values containing a properly formatted, valid `number` value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**Date time-based comparators** (BEFORE / AFTER)
* accept `Date` values, which are automatically converted to a second-based Unix timestamp,
* accept `number` values representing a second-based Unix timestamp,
* accept `string` values containing a properly formatted, valid `number` value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**String array-based comparators** (ARRAY CONTAINS ANY OF / ARRAY NOT CONTAINS ANY OF)
* accept arrays of `string`,
* accept `string` values containing a valid JSON string which can be deserialized to an array of `string`,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

### Default user

It's possible to set a default user object that will be used on feature flag and setting evaluation. It can be useful when your application has a single user only or rarely switches users.
Expand Down Expand Up @@ -495,13 +535,11 @@ const configCatClient = configcat.getClient(
### Setting log levels

```js
const logger = configcat.createConsoleLogger(configcat.LogLevel.Info); // Setting log level to Info

const configCatClient = configcat.getClient(
'#YOUR-SDK-KEY#',
configcat.PollingMode.AutoPoll,
{
logger: logger,
logger: configcat.createConsoleLogger(configcat.LogLevel.Info) // Setting log level to Info
},
);
```
Expand All @@ -519,11 +557,11 @@ Available log levels:
Info level logging helps to inspect the feature flag evaluation process:

```bash
ConfigCat - INFO - [5000] Evaluate 'isPOCFeatureEnabled'
User : {"identifier":"#SOME-USER-ID#","email":"[email protected]"}
Evaluating rule: '[email protected]' CONTAINS '@something.com' => no match
Evaluating rule: '[email protected]' CONTAINS '@example.com' => MATCH
Returning value : true
ConfigCat - INFO - [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier":"#SOME-USER-ID#","Email":"[email protected]"}'
Evaluating targeting rules and applying the first match if any:
- IF User.Email CONTAINS ANY OF ['@something.com'] THEN 'false' => no match
- IF User.Email CONTAINS ANY OF ['@example.com'] THEN 'true' => MATCH, applying rule
Returning 'true'.
```
## `getAllKeysAsync()`
Expand Down Expand Up @@ -578,7 +616,7 @@ settingValues.forEach((details) => console.log(details));
## Snapshots and synchronous feature flag evaluation
On JavaScript platforms, the _ConfigCat_ client provides only asynchronous methods for evaluating feature flags and settings
because these operations may involve network communication (downloading config data from the ConfigCat CDN servers),
because these operations may involve network communication (e.g. downloading config data from the ConfigCat CDN servers),
which is necessarily an asynchronous operation in JavaScript.
However, there may be use cases where synchronous evaluation is preferable, thus, since v7.1.0, the JavaScript (SSR) SDK provides a way
Expand All @@ -602,6 +640,14 @@ for (const key of snapshot.getAllKeys()) {
}
```
:::caution
Please note that when you create and utilize a snapshot, it won't refresh your local cache once the cached config data expires.
Additionally, when working with [shared caching](/docs/advanced/caching/#shared-cache), creating a snapshot also doesn't
trigger a sync with the external cache, since the snapshot only captures the config instance stored in the client's memory.
Therefore, it's recommended to use snapshots in conjunction with the Auto Polling mode, where the SDK automatically updates the local cache
in the background. For other polling modes, you'll need to manually initiate a cache refresh by invoking `forceRefreshAsync`.
:::
In Auto Poll mode, you can use the `waitForReady` method to wait for that latest config data to become available locally:
```js
Expand Down
80 changes: 63 additions & 17 deletions website/docs/sdk-reference/js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -258,8 +258,8 @@ The `details` result contains the following information:
| `isDefaultValue` | `boolean` | True when the default value passed to `getValueDetailsAsync()` is returned due to an error. |
| `errorMessage` | `string` | In case of an error, this field contains the error message. |
| `errorException` | `any` | In case of an error, this field contains the related exception object (if any). |
| `matchedEvaluationRule` | `RolloutRule` | If the evaluation was based on a targeting rule, this field contains that specific rule. |
| `matchedEvaluationPercentageRule` | `RolloutPercentageItem` | If the evaluation was based on a percentage rule, this field contains that specific rule. |
| `matchedTargetingRule` | `ITargetingRule` | The targeting rule (if any) that matched during the evaluation and was used to return the evaluated value. |
| `matchedPercentageOption` | `IPercentageOption` | The percentage option (if any) that was used to select the evaluated value. |
| `fetchTime` | `Date` | The last download time (UTC) of the current config. |

## User Object
Expand All @@ -276,12 +276,12 @@ let userObject = new configcat.User('#UNIQUE-USER-IDENTIFIER#');
let userObject = new configcat.User('[email protected]');
```

| Parameters | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | **REQUIRED.** Unique identifier of a user in your application. Can be any `string` value, even an email address. |
| `email` | Optional parameter for easier targeting rule definitions. |
| `country` | Optional parameter for easier targeting rule definitions. |
| `custom` | Optional `dictionary of strings` representing the custom attributes of a user for advanced targeting rule definitions. e.g. User role, Subscription type. |
| Parameters | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | **REQUIRED.** Unique identifier of a user in your application. Can be any `string` value, even an email address. |
| `email` | Optional parameter for easier targeting rule definitions. |
| `country` | Optional parameter for easier targeting rule definitions. |
| `custom` | Optional dictionary for custom attributes of a user for advanced targeting rule definitions. E.g. User role, Subscription type. |

For advanced targeting:

Expand All @@ -297,6 +297,46 @@ let userObject = new configcat.User(
);
```

The `custom` dictionary also allows attribute values other than `string` values:

```js
let userObject = new configcat.User("#UNIQUE-USER-IDENTIFIER#");
userObject.custom = {
Rating: 4.5,
RegisteredAt: new Date("2023-11-22T12:34:56.000Z"),
Roles: ["Role1", "Role2"]
};
```

### User Object Attribute Types

All comparators support `string` values as User Object attribute (in some cases they need to be provided in a specific format though, see below),
but some of them also support other types of values. It depends on the comparator how the values will be handled. The following rules apply:

**Text-based comparators** (EQUALS, IS ONE OF, etc.)
* accept `string` values,
* all other values are automatically converted to `string` (a warning will be logged but evaluation will continue as normal).

**SemVer-based comparators** (IS ONE OF, <, >=, etc.)
* accept `string` values containing a properly formatted, valid semver value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**Number-based comparators** (=, <, >=, etc.)
* accept `number` values,
* accept `string` values containing a properly formatted, valid `number` value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**Date time-based comparators** (BEFORE / AFTER)
* accept `Date` values, which are automatically converted to a second-based Unix timestamp,
* accept `number` values representing a second-based Unix timestamp,
* accept `string` values containing a properly formatted, valid `number` value,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

**String array-based comparators** (ARRAY CONTAINS ANY OF / ARRAY NOT CONTAINS ANY OF)
* accept arrays of `string`,
* accept `string` values containing a valid JSON string which can be deserialized to an array of `string`,
* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped).

### Default user

It's possible to set a default user object that will be used on feature flag and setting evaluation. It can be useful when your application has a single user only or rarely switches users.
Expand Down Expand Up @@ -517,13 +557,11 @@ const configCatClient = configcat.getClient(
### Setting log levels

```js
const logger = configcat.createConsoleLogger(configcat.LogLevel.Info); // Setting log level to Info

const configCatClient = configcat.getClient(
'#YOUR-SDK-KEY#',
configcat.PollingMode.AutoPoll,
{
logger: logger,
logger: configcat.createConsoleLogger(configcat.LogLevel.Info) // Setting log level to Info
},
);
```
Expand All @@ -541,11 +579,11 @@ Available log levels:
Info level logging helps to inspect the feature flag evaluation process:

```bash
ConfigCat - INFO - [5000] Evaluate 'isPOCFeatureEnabled'
User : {"identifier":"#SOME-USER-ID#","email":"[email protected]"}
Evaluating rule: '[email protected]' CONTAINS '@something.com' => no match
Evaluating rule: '[email protected]' CONTAINS '@example.com' => MATCH
Returning value : true
ConfigCat - INFO - [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier":"#SOME-USER-ID#","Email":"[email protected]"}'
Evaluating targeting rules and applying the first match if any:
- IF User.Email CONTAINS ANY OF ['@something.com'] THEN 'false' => no match
- IF User.Email CONTAINS ANY OF ['@example.com'] THEN 'true' => MATCH, applying rule
Returning 'true'.
```
## `getAllKeysAsync()`
Expand Down Expand Up @@ -600,7 +638,7 @@ settingValues.forEach((details) => console.log(details));
## Snapshots and synchronous feature flag evaluation
On JavaScript platforms, the _ConfigCat_ client provides only asynchronous methods for evaluating feature flags and settings
because these operations may involve network communication (downloading config data from the ConfigCat CDN servers),
because these operations may involve network communication (e.g. downloading config data from the ConfigCat CDN servers),
which is necessarily an asynchronous operation in JavaScript.
However, there may be use cases where synchronous evaluation is preferable, thus, since v8.1.0, the JavaScript SDK provides a way
Expand All @@ -624,6 +662,14 @@ for (const key of snapshot.getAllKeys()) {
}
```
:::caution
Please note that when you create and utilize a snapshot, it won't refresh your local cache once the cached config data expires.
Additionally, when working with [shared caching](/docs/advanced/caching/#shared-cache), creating a snapshot also doesn't
trigger a sync with the external cache, since the snapshot only captures the config instance stored in the client's memory.
Therefore, it's recommended to use snapshots in conjunction with the Auto Polling mode, where the SDK automatically updates the local cache
in the background. For other polling modes, you'll need to manually initiate a cache refresh by invoking `forceRefreshAsync`.
:::
In Auto Poll mode, you can use the `waitForReady` method to wait for that latest config data to become available locally:
```js
Expand Down
Loading

0 comments on commit 7320474

Please sign in to comment.