diff --git a/index.ts b/index.ts index 1e1f0e9..cf24b7c 100644 --- a/index.ts +++ b/index.ts @@ -5,6 +5,7 @@ export { FlagsmithClientError, EnvironmentDataPollingManager, FlagsmithCache, + BaseFlag, DefaultFlag, Flags, Flagsmith @@ -12,7 +13,7 @@ export { export { BaseOfflineHandler, LocalFileHandler } from './sdk/offline_handlers.js'; -export { FlagsmithConfig } from './sdk/types.js'; +export { FlagsmithConfig, FlagsmithValue, TraitConfig } from './sdk/types.js'; export { EnvironmentModel, diff --git a/sdk/index.ts b/sdk/index.ts index 95d2f27..e299288 100644 --- a/sdk/index.ts +++ b/sdk/index.ts @@ -22,14 +22,14 @@ import { FlagsmithCache, FlagsmithConfig, FlagsmithTraitValue, - ITraitConfig + TraitConfig } from './types.js'; import { pino, Logger } from 'pino'; export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js'; export { FlagsmithAPIError, FlagsmithClientError } from './errors.js'; -export { DefaultFlag, Flags } from './models.js'; +export { BaseFlag, DefaultFlag, Flags } from './models.js'; export { EnvironmentDataPollingManager } from './polling_manager.js'; export { FlagsmithCache, FlagsmithConfig } from './types.js'; @@ -206,13 +206,13 @@ export class Flagsmith { * * @param {string} identifier a unique identifier for the identity in the current environment, e.g. email address, username, uuid - * @param {{[key:string]:any | ITraitConfig}} traits? a dictionary of traits to add / update on the identity in + * @param {{[key:string]:any | TraitConfig}} traits? a dictionary of traits to add / update on the identity in Flagsmith, e.g. {"num_orders": 10} or {age: {value: 30, transient: true}} * @returns Flags object holding all the flags for the given identity. */ async getIdentityFlags( identifier: string, - traits?: { [key: string]: FlagsmithTraitValue | ITraitConfig }, + traits?: { [key: string]: FlagsmithTraitValue | TraitConfig }, transient: boolean = false ): Promise { if (!identifier) { @@ -456,7 +456,7 @@ export class Flagsmith { private async getIdentityFlagsFromApi( identifier: string, - traits: { [key: string]: FlagsmithTraitValue | ITraitConfig }, + traits: { [key: string]: FlagsmithTraitValue | TraitConfig }, transient: boolean = false ) { if (!this.identitiesUrl) { diff --git a/sdk/models.ts b/sdk/models.ts index fab5b74..90cffae 100644 --- a/sdk/models.ts +++ b/sdk/models.ts @@ -3,9 +3,21 @@ import { AnalyticsProcessor } from './analytics.js'; type FlagValue = string | number | boolean | undefined; +/** + * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}. + */ export class BaseFlag { + /** + * Indicates whether this feature is enabled. + */ enabled: boolean; + /** + * An optional {@link FlagValue} for this feature. + */ value: FlagValue; + /** + * If true, the state for this feature was determined by a default flag handler. See {@link DefaultFlag}. + */ isDefault: boolean; constructor(value: FlagValue, enabled: boolean, isDefault: boolean) { @@ -15,14 +27,27 @@ export class BaseFlag { } } +/** + * A {@link BaseFlag} returned by a default flag handler when flag evaluation fails. + * @see FlagsmithConfig#defaultFlagHandler + */ export class DefaultFlag extends BaseFlag { constructor(value: FlagValue, enabled: boolean) { super(value, enabled, true); } } +/** + * A Flagsmith feature retrieved from a successful flag evaluation. + */ export class Flag extends BaseFlag { + /** + * An identifier for this feature, unique in a single Flagsmith installation. + */ featureId: number; + /** + * The programmatic name for this feature, unique per Flagsmith project. + */ featureName: string; constructor(params: { diff --git a/sdk/types.ts b/sdk/types.ts index 512b6c8..ac801b3 100644 --- a/sdk/types.ts +++ b/sdk/types.ts @@ -5,7 +5,10 @@ import { Logger } from 'pino'; import { BaseOfflineHandler } from './offline_handlers.js'; import { Flagsmith } from './index.js'; -export type IFlagsmithValue = T; +/** + * A concrete type for the possible values of a feature. + */ +export type FlagsmithValue = T; /** * Stores and retrieves {@link Flags} from a cache. @@ -95,7 +98,7 @@ export interface FlagsmithConfig { * const defaultHandler = () => new DefaultFlag(undefined, false) * * // Enable only VIP flags by default - * const vipDefaultHandler = (key: string) => new Default(undefined, key.startsWith('vip_')) + * const vipDefaultHandler = (key: string) => new DefaultFlag(undefined, key.startsWith('vip_')) */ defaultFlagHandler?: (flagKey: string) => DefaultFlag; cache?: FlagsmithCache; @@ -116,9 +119,16 @@ export interface FlagsmithConfig { offlineHandler?: BaseOfflineHandler; } -export interface ITraitConfig { +/** + * Represents the configuration for a trait in Flagsmith. + * + * @property value The {@link FlagsmithTraitValue} for this trait. + * @property [transient] Indicates whether the trait should be persisted when used in a remote flag evaluation context. + * Defaults to false. + */ +export interface TraitConfig { value: FlagsmithTraitValue; transient?: boolean; } -export declare type FlagsmithTraitValue = IFlagsmithValue; +export declare type FlagsmithTraitValue = FlagsmithValue; diff --git a/sdk/utils.ts b/sdk/utils.ts index 082a661..286677a 100644 --- a/sdk/utils.ts +++ b/sdk/utils.ts @@ -1,11 +1,11 @@ -import { Fetch, FlagsmithTraitValue, ITraitConfig } from './types.js'; +import { Fetch, FlagsmithTraitValue, TraitConfig } from './types.js'; import { Dispatcher } from 'undici-types'; -type Traits = { [key: string]: ITraitConfig | FlagsmithTraitValue }; +type Traits = { [key: string]: TraitConfig | FlagsmithTraitValue }; export function isTraitConfig( - traitValue: ITraitConfig | FlagsmithTraitValue -): traitValue is ITraitConfig { + traitValue: TraitConfig | FlagsmithTraitValue +): traitValue is TraitConfig { return !!traitValue && typeof traitValue == 'object' && traitValue.value !== undefined; }