@productcraft/flags 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +35 -0
  2. package/api.md +110 -18
  3. package/dist/browser/{chunk-4LRAE3F3.js → chunk-OOX7EUCT.js} +114 -22
  4. package/dist/browser/chunk-OOX7EUCT.js.map +1 -0
  5. package/dist/browser/{chunk-72WU42RU.js → chunk-WUZAG2E3.js} +11 -4
  6. package/dist/browser/chunk-WUZAG2E3.js.map +1 -0
  7. package/dist/browser/{chunk-FXZVXQ75.cjs → chunk-XZK57G7L.cjs} +114 -22
  8. package/dist/browser/chunk-XZK57G7L.cjs.map +1 -0
  9. package/dist/browser/{chunk-4XCQBTYE.cjs → chunk-YM5K4NHA.cjs} +11 -4
  10. package/dist/browser/chunk-YM5K4NHA.cjs.map +1 -0
  11. package/dist/browser/index.cjs +8 -8
  12. package/dist/browser/index.js +2 -2
  13. package/dist/browser/management.cjs +2 -2
  14. package/dist/browser/management.js +1 -1
  15. package/dist/browser/testing.cjs +3 -3
  16. package/dist/browser/testing.cjs.map +1 -1
  17. package/dist/browser/testing.js +1 -1
  18. package/dist/browser/testing.js.map +1 -1
  19. package/dist/{chunk-TSRLPHJ5.js → chunk-CGVDMKEE.js} +12 -5
  20. package/dist/chunk-CGVDMKEE.js.map +1 -0
  21. package/dist/{chunk-QTDMUNLG.cjs → chunk-L3AOANTB.cjs} +12 -5
  22. package/dist/chunk-L3AOANTB.cjs.map +1 -0
  23. package/dist/{chunk-WI4EZXOV.cjs → chunk-RJIVAOBG.cjs} +114 -22
  24. package/dist/chunk-RJIVAOBG.cjs.map +1 -0
  25. package/dist/{chunk-2YRDLKNB.js → chunk-XNJ5OX4X.js} +114 -22
  26. package/dist/chunk-XNJ5OX4X.js.map +1 -0
  27. package/dist/{client-K2zALPGD.d.cts → client-BBiIKiGW.d.cts} +18 -14
  28. package/dist/{client-K2zALPGD.d.ts → client-BBiIKiGW.d.ts} +18 -14
  29. package/dist/{client-bVEJfS6_.d.cts → client-BWi7PASW.d.cts} +1091 -45
  30. package/dist/{client-bVEJfS6_.d.ts → client-BWi7PASW.d.ts} +1091 -45
  31. package/dist/index.cjs +8 -8
  32. package/dist/index.d.cts +3 -3
  33. package/dist/index.d.ts +3 -3
  34. package/dist/index.js +2 -2
  35. package/dist/management.cjs +2 -2
  36. package/dist/management.d.cts +1 -1
  37. package/dist/management.d.ts +1 -1
  38. package/dist/management.js +1 -1
  39. package/dist/testing.cjs +3 -3
  40. package/dist/testing.cjs.map +1 -1
  41. package/dist/testing.d.cts +3 -3
  42. package/dist/testing.d.ts +3 -3
  43. package/dist/testing.js +1 -1
  44. package/dist/testing.js.map +1 -1
  45. package/manifest.json +1 -1
  46. package/package.json +2 -2
  47. package/dist/browser/chunk-4LRAE3F3.js.map +0 -1
  48. package/dist/browser/chunk-4XCQBTYE.cjs.map +0 -1
  49. package/dist/browser/chunk-72WU42RU.js.map +0 -1
  50. package/dist/browser/chunk-FXZVXQ75.cjs.map +0 -1
  51. package/dist/chunk-2YRDLKNB.js.map +0 -1
  52. package/dist/chunk-QTDMUNLG.cjs.map +0 -1
  53. package/dist/chunk-TSRLPHJ5.js.map +0 -1
  54. package/dist/chunk-WI4EZXOV.cjs.map +0 -1
@@ -1,5 +1,5 @@
1
1
  import { Logger, ProductCraftError } from '@productcraft/core';
2
- import { SettingValue, User, EvaluationDetails, ParsedConfig } from '@productcraft/flags-engine';
2
+ import { SettingValue, UserInput, EvaluationDetails, ParsedConfig } from '@productcraft/flags-engine';
3
3
 
4
4
  type Layer = "CACHED" | "STALE" | null;
5
5
 
@@ -63,12 +63,16 @@ interface FlagsClientOptions {
63
63
  bootstrap?: string | object;
64
64
  overrides?: FlagsOverrides;
65
65
  /** The user evaluations are for when a call passes none. A call's own user replaces it as a whole. */
66
- defaultUser?: User;
67
- /** Where warnings and errors are logged. Default `console`. Pass `null` to log nothing. */
66
+ defaultUser?: UserInput;
67
+ /** Where warnings and errors are logged. Default `console`. Pass `null` to log nothing. Evaluation warnings (soft misses such as a missing attribute) are logged once per attribute for the life of the client. */
68
68
  logger?: Logger | null;
69
69
  /** Custom `fetch`. Defaults to the global `fetch`. */
70
70
  fetch?: typeof fetch;
71
- /** Delivery host. Defaults to `https://api.flags.productcraft.co`; when set, `delivery.base_urls` hints are ignored. */
71
+ /**
72
+ * Delivery host. Defaults to `https://api.flags.productcraft.co`. Set it for an in-cluster or self-hosted address,
73
+ * an egress proxy or your own CDN; when set, the config's `delivery.base_urls` hints are ignored, so the client only
74
+ * ever downloads from this host.
75
+ */
72
76
  baseUrl?: string;
73
77
  /** Start without network access (the cache, `bootstrap` and overrides still apply). `setOnline()` starts fetching. */
74
78
  offline?: boolean;
@@ -118,17 +122,17 @@ declare class FlagsClientError extends ProductCraftError {
118
122
  declare class FlagsSnapshot {
119
123
  #private;
120
124
  /** @internal */
121
- constructor(config: ParsedConfig | null, raw: Obj | null, user: User | undefined, layer: Layer);
125
+ constructor(config: ParsedConfig | null, raw: Obj | null, user: UserInput | undefined, layer: Layer);
122
126
  /** Revision of the config, 0 when there is none. */
123
127
  get revision(): number;
124
128
  /** Generation of the config (bumped after a database restore), 0 when there is none. */
125
129
  get generation(): number;
126
130
  /** Setting keys in config order. */
127
131
  keys(): string[];
128
- getValue<D extends Def>(key: string, defaultValue: D, user?: User | null): FlagValue<D>;
129
- getValueDetails<D extends Def>(key: string, defaultValue: D, user?: User | null): EvaluationDetails<FlagValue<D>>;
130
- getJson<T = unknown>(key: string, defaultValue: T, user?: User | null): T;
131
- getAllValues(user?: User | null): Record<string, unknown>;
132
+ getValue<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): FlagValue<D>;
133
+ getValueDetails<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): EvaluationDetails<FlagValue<D>>;
134
+ getJson<T = unknown>(key: string, defaultValue: T, user?: UserInput | null): T;
135
+ getAllValues(user?: UserInput | null): Record<string, unknown>;
132
136
  /** The config JSON this snapshot evaluates (overrides included), or null: pass it as another client's `bootstrap`. */
133
137
  toJSON(): Obj | null;
134
138
  }
@@ -151,15 +155,15 @@ declare class FlagsClient {
151
155
  on<E extends keyof FlagsClientEvents>(event: E, listener: FlagsClientEvents[E]): () => void;
152
156
  off<E extends keyof FlagsClientEvents>(event: E, listener: FlagsClientEvents[E]): void;
153
157
  /** The user evaluations use when a call passes none. */
154
- setDefaultUser(user: User | undefined): void;
158
+ setDefaultUser(user: UserInput | undefined): void;
155
159
  /** The value of a flag or setting for a user; the default on any failure. Never throws. */
156
- getValue<D extends Def>(key: string, defaultValue: D, user?: User | null): Promise<FlagValue<D>>;
160
+ getValue<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): Promise<FlagValue<D>>;
157
161
  /** The value plus why: reason, matched rule or split, error code, warnings and revision. Never throws. */
158
- getValueDetails<D extends Def>(key: string, defaultValue: D, user?: User | null): Promise<EvaluationDetails<FlagValue<D>>>;
162
+ getValueDetails<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): Promise<EvaluationDetails<FlagValue<D>>>;
159
163
  /** A json (or string) setting, parsed. A parse failure, a missing key or another type returns the default. Never throws. */
160
- getJson<T = unknown>(key: string, defaultValue: T, user?: User | null): Promise<T>;
164
+ getJson<T = unknown>(key: string, defaultValue: T, user?: UserInput | null): Promise<T>;
161
165
  /** Every setting's value for a user (json settings parsed), as a null-prototype object. Never throws. */
162
- getAllValues(user?: User | null): Promise<Record<string, unknown>>;
166
+ getAllValues(user?: UserInput | null): Promise<Record<string, unknown>>;
163
167
  /** The config as it is now, for synchronous evaluation. Does not wait for the first download. */
164
168
  snapshot(): FlagsSnapshot;
165
169
  /** Resolves when start-up has settled: the first download finished or `maxInitWaitSeconds` passed. Never rejects. */
@@ -1,5 +1,5 @@
1
1
  import { Logger, ProductCraftError } from '@productcraft/core';
2
- import { SettingValue, User, EvaluationDetails, ParsedConfig } from '@productcraft/flags-engine';
2
+ import { SettingValue, UserInput, EvaluationDetails, ParsedConfig } from '@productcraft/flags-engine';
3
3
 
4
4
  type Layer = "CACHED" | "STALE" | null;
5
5
 
@@ -63,12 +63,16 @@ interface FlagsClientOptions {
63
63
  bootstrap?: string | object;
64
64
  overrides?: FlagsOverrides;
65
65
  /** The user evaluations are for when a call passes none. A call's own user replaces it as a whole. */
66
- defaultUser?: User;
67
- /** Where warnings and errors are logged. Default `console`. Pass `null` to log nothing. */
66
+ defaultUser?: UserInput;
67
+ /** Where warnings and errors are logged. Default `console`. Pass `null` to log nothing. Evaluation warnings (soft misses such as a missing attribute) are logged once per attribute for the life of the client. */
68
68
  logger?: Logger | null;
69
69
  /** Custom `fetch`. Defaults to the global `fetch`. */
70
70
  fetch?: typeof fetch;
71
- /** Delivery host. Defaults to `https://api.flags.productcraft.co`; when set, `delivery.base_urls` hints are ignored. */
71
+ /**
72
+ * Delivery host. Defaults to `https://api.flags.productcraft.co`. Set it for an in-cluster or self-hosted address,
73
+ * an egress proxy or your own CDN; when set, the config's `delivery.base_urls` hints are ignored, so the client only
74
+ * ever downloads from this host.
75
+ */
72
76
  baseUrl?: string;
73
77
  /** Start without network access (the cache, `bootstrap` and overrides still apply). `setOnline()` starts fetching. */
74
78
  offline?: boolean;
@@ -118,17 +122,17 @@ declare class FlagsClientError extends ProductCraftError {
118
122
  declare class FlagsSnapshot {
119
123
  #private;
120
124
  /** @internal */
121
- constructor(config: ParsedConfig | null, raw: Obj | null, user: User | undefined, layer: Layer);
125
+ constructor(config: ParsedConfig | null, raw: Obj | null, user: UserInput | undefined, layer: Layer);
122
126
  /** Revision of the config, 0 when there is none. */
123
127
  get revision(): number;
124
128
  /** Generation of the config (bumped after a database restore), 0 when there is none. */
125
129
  get generation(): number;
126
130
  /** Setting keys in config order. */
127
131
  keys(): string[];
128
- getValue<D extends Def>(key: string, defaultValue: D, user?: User | null): FlagValue<D>;
129
- getValueDetails<D extends Def>(key: string, defaultValue: D, user?: User | null): EvaluationDetails<FlagValue<D>>;
130
- getJson<T = unknown>(key: string, defaultValue: T, user?: User | null): T;
131
- getAllValues(user?: User | null): Record<string, unknown>;
132
+ getValue<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): FlagValue<D>;
133
+ getValueDetails<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): EvaluationDetails<FlagValue<D>>;
134
+ getJson<T = unknown>(key: string, defaultValue: T, user?: UserInput | null): T;
135
+ getAllValues(user?: UserInput | null): Record<string, unknown>;
132
136
  /** The config JSON this snapshot evaluates (overrides included), or null: pass it as another client's `bootstrap`. */
133
137
  toJSON(): Obj | null;
134
138
  }
@@ -151,15 +155,15 @@ declare class FlagsClient {
151
155
  on<E extends keyof FlagsClientEvents>(event: E, listener: FlagsClientEvents[E]): () => void;
152
156
  off<E extends keyof FlagsClientEvents>(event: E, listener: FlagsClientEvents[E]): void;
153
157
  /** The user evaluations use when a call passes none. */
154
- setDefaultUser(user: User | undefined): void;
158
+ setDefaultUser(user: UserInput | undefined): void;
155
159
  /** The value of a flag or setting for a user; the default on any failure. Never throws. */
156
- getValue<D extends Def>(key: string, defaultValue: D, user?: User | null): Promise<FlagValue<D>>;
160
+ getValue<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): Promise<FlagValue<D>>;
157
161
  /** The value plus why: reason, matched rule or split, error code, warnings and revision. Never throws. */
158
- getValueDetails<D extends Def>(key: string, defaultValue: D, user?: User | null): Promise<EvaluationDetails<FlagValue<D>>>;
162
+ getValueDetails<D extends Def>(key: string, defaultValue: D, user?: UserInput | null): Promise<EvaluationDetails<FlagValue<D>>>;
159
163
  /** A json (or string) setting, parsed. A parse failure, a missing key or another type returns the default. Never throws. */
160
- getJson<T = unknown>(key: string, defaultValue: T, user?: User | null): Promise<T>;
164
+ getJson<T = unknown>(key: string, defaultValue: T, user?: UserInput | null): Promise<T>;
161
165
  /** Every setting's value for a user (json settings parsed), as a null-prototype object. Never throws. */
162
- getAllValues(user?: User | null): Promise<Record<string, unknown>>;
166
+ getAllValues(user?: UserInput | null): Promise<Record<string, unknown>>;
163
167
  /** The config as it is now, for synchronous evaluation. Does not wait for the first download. */
164
168
  snapshot(): FlagsSnapshot;
165
169
  /** Resolves when start-up has settled: the first download finished or `maxInitWaitSeconds` passed. Never rejects. */