showwhat 2.0.0 → 2.1.0

package/README.md

@@ -1,8 +1,21 @@
 # showwhat
 
-Feature flags and config you own. Platform-agnostic.
+Schema and rule engine for **feature flags** and **config** resolution
+<br />Inspired by OpenAPI and Swagger
 
-`showwhat` combines a YAML/JSON definition format with a schema-validated, extensible rule engine. Define flags and config as variations with conditions, evaluate them in your app, and store definitions wherever you want.
+## Features
+
+- Define flags and config as [definitions](https://showwhat.yeojz.dev/docs/definitions) and declare which [variation](https://showwhat.yeojz.dev/docs/variations) is served based on [conditions](https://showwhat.yeojz.dev/docs/conditions).
+- TypeScript-first with Zod validation.
+- Supports `booleans`, `strings`, `numbers`, `arrays` and `objects` as resolved variation values.
+- Supports both `yaml` or `json`.
+- Runtime evaluation against user defined [context](https://showwhat.yeojz.dev/docs/context).
+- Supports [annotations](https://showwhat.yeojz.dev/docs/annotations) for condition chaining and cross-dependency.
+- Ability to define [presets](https://showwhat.yeojz.dev/docs/presets.html) for condition reuse.
+- Extensible with [custom conditions](https://showwhat.yeojz.dev/docs/custom-conditions).
+- Store definitions in files and manage them in version control or serve them from an API.
+
+A browser based schema [configurator](https://showwhat.yeojz.dev/configurator/) is also provided / available.
 
 ## Installation
 
@@ -18,9 +31,43 @@ deno install npm:showwhat
 
 ## Quick start
 
+### 1. Define your flags
+
+Definitions can be YAML files or plain objects. Each definition has **variations** evaluated top-to-bottom — the first match wins.
+
+```yaml
+# flags.yaml
+definitions:
+  checkout_v2:
+    variations:
+      - value: true
+        conditions:
+          - type: env
+            value: prod
+      - value: false # default — no conditions means always matches
+
+  max_upload_size:
+    variations:
+      - value: 100
+        conditions:
+          - type: number
+            key: tier_level
+            op: gte
+            value: 2
+      - value: 25
+```
+
+### 2. Load definitions
+
+Use `MemoryData` to load definitions from YAML strings or plain objects:
+
 ```ts
-import { MemoryData, showwhat } from "showwhat";
+import { MemoryData } from "showwhat";
 
+// From a YAML string
+const data = await MemoryData.fromYaml(fs.readFileSync("flags.yaml", "utf8"));
+
+// Or from a plain object
 const data = await MemoryData.fromObject({
   definitions: {
     checkout_v2: {
@@ -28,23 +75,95 @@ const data = await MemoryData.fromObject({
     },
   },
 });
+```
+
+### 3. Resolve flags
+
+Pass a runtime **context** and the keys you want to resolve:
+
+```ts
+import { showwhat } from "showwhat";
 
 const results = await showwhat({
-  keys: ["checkout_v2"],
-  context: { env: "prod" },
+  keys: ["checkout_v2", "max_upload_size"],
+  context: { env: "prod", tier_level: 3 },
   options: { data },
 });
-console.log(results.checkout_v2.value); // true
 ```
 
-## Features
+Omit `keys` to resolve all definitions at once.
+
+### 4. Use the results
+
+Every result entry is either `{ success: true, value }` or `{ success: false, error }`:
+
+```ts
+const flag = results["checkout_v2"];
+if (flag.success) {
+  console.log(flag.value); // true
+}
+
+const upload = results["max_upload_size"];
+if (upload.success) {
+  console.log(upload.value); // 100
+}
+```
+
+### Built-in condition types
+
+| Type       | Description                          | Example                                                              |
+| ---------- | ------------------------------------ | -------------------------------------------------------------------- |
+| `env`      | Shorthand for matching `context.env` | `{ type: env, value: prod }`                                         |
+| `string`   | Compare any string key               | `{ type: string, key: tier, op: eq, value: pro }`                    |
+| `number`   | Compare any numeric key              | `{ type: number, key: level, op: gte, value: 2 }`                    |
+| `bool`     | Compare any boolean key              | `{ type: bool, key: mobile, value: true }`                           |
+| `datetime` | Compare any datetime key             | `{ type: datetime, key: at, op: gt, value: "2025-01-01T00:00:00Z" }` |
+| `startAt`  | Passes when `context.at >= value`    | `{ type: startAt, value: "2025-06-01T00:00:00Z" }`                   |
+| `endAt`    | Passes when `context.at < value`     | `{ type: endAt, value: "2025-07-01T00:00:00Z" }`                     |
+| `and`      | All child conditions must pass       | `{ type: and, conditions: [...] }`                                   |
+| `or`       | Any child condition must pass        | `{ type: or, conditions: [...] }`                                    |
+
+### Presets
+
+Presets define reusable condition shorthands to keep definitions DRY:
+
+```yaml
+definitions:
+  premium_feature:
+    variations:
+      - value: true
+        conditions:
+          - type: tier
+            op: in
+            value: [pro, enterprise]
+      - value: false
+
+presets:
+  tier:
+    type: string
+    key: tier
+```
 
-- `showwhat()` resolution engine for flags and config values
-- Built-in condition evaluators: `string`, `number`, `datetime`, `bool`, `env`, `startAt`, `endAt`
-- Custom evaluators via `registerEvaluators()`
-- YAML and JSON parsing with schema validation
-- Pluggable data sources (`DefinitionReader` / `DefinitionWriter`)
-- Typed error hierarchy
+### Custom conditions
+
+Register your own evaluators to extend the built-in condition types:
+
+```ts
+import { showwhat, registerEvaluators, MemoryData } from "showwhat";
+
+const evaluators = registerEvaluators({
+  percentage: async ({ condition, context }) => {
+    const hash = someHash(context.userId);
+    return hash % 100 < condition.value;
+  },
+});
+
+const results = await showwhat({
+  keys: ["gradual_rollout"],
+  context: { userId: "user-123" },
+  options: { data, evaluators },
+});
+```
 
 ## Documentation
 
@@ -52,7 +171,6 @@ console.log(results.checkout_v2.value); // true
 - [Conditions](https://showwhat.yeojz.dev/docs/conditions) — built-in condition types and usage
 - [Context](https://showwhat.yeojz.dev/docs/context) — runtime context object
 - [Definitions](https://showwhat.yeojz.dev/docs/definitions) — definition structure and variations
-- [Core API](https://showwhat.yeojz.dev/docs/core) — `showwhat()`, `resolve()`, parsing, and more
 - [Errors](https://showwhat.yeojz.dev/docs/errors) — error types and when they are thrown
 - [Custom Conditions](https://showwhat.yeojz.dev/docs/custom-conditions) — writing your own evaluators
 - [Custom Data Sources](https://showwhat.yeojz.dev/docs/custom-data-sources) — implementing `DefinitionReader`

package/dist/index.d.ts

@@ -1,16 +1,21 @@
-import { Resolution, ResolutionError, ResolverOptions, DefinitionReader, ConditionEvaluators, BuiltinCondition, ContextValue, Context, Dependencies } from '@showwhat/core';
+import { Resolution, ResolutionError, ResolverOptions, DefinitionReader, PresetReader, Presets, ConditionEvaluators, Context, Dependencies } from '@showwhat/core';
 export * from '@showwhat/core';
 
 type ShowWhatOptions = ResolverOptions & {
     data: DefinitionReader;
 };
 type Resolutions = Record<string, Resolution | ResolutionError>;
-declare function showwhat<T extends Record<string, ContextValue> = Record<string, ContextValue>, D extends Record<string, unknown> = Record<string, unknown>>({ keys, context, deps, options, }: {
+declare function showwhat({ keys, context, deps, options, }: {
     keys?: string[];
-    context: Context<T>;
-    deps?: Dependencies<D>;
+    context: Context;
+    deps?: Dependencies;
     options: ShowWhatOptions;
 }): Promise<Resolutions>;
-declare function registerEvaluators<T extends string>(extra: ConditionEvaluators<T>): ConditionEvaluators<BuiltinCondition["type"] | T>;
+declare function mergePresets({ key, presets, overrides, }: {
+    key?: string;
+    presets?: PresetReader;
+    overrides?: Presets;
+}): Promise<Presets>;
+declare function registerEvaluators(extra: ConditionEvaluators): ConditionEvaluators;
 
-export { type Resolutions, type ShowWhatOptions, registerEvaluators, showwhat };
+export { type Resolutions, type ShowWhatOptions, mergePresets, registerEvaluators, showwhat };

package/dist/index.js

@@ -50,7 +50,23 @@ async function showwhat({
     }
   });
 }
-var COMPOSITE_TYPES = /* @__PURE__ */ new Set(["and", "or"]);
+async function mergePresets({
+  key,
+  presets,
+  overrides
+}) {
+  if (!presets) {
+    return {
+      ...overrides
+    };
+  }
+  const base = key ? await presets.getPresets(key) : await presets.getPresets();
+  return {
+    ...base,
+    ...overrides
+  };
+}
+var COMPOSITE_TYPES = /* @__PURE__ */ new Set(["and", "or", "checkAnnotations"]);
 function registerEvaluators(extra) {
   for (const key of Object.keys(extra)) {
     if (COMPOSITE_TYPES.has(key)) {
@@ -60,6 +76,7 @@ function registerEvaluators(extra) {
   return { ...builtinEvaluators, ...extra };
 }
 export {
+  mergePresets,
   registerEvaluators,
   showwhat
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  ContextSchema,\n  builtinEvaluators,\n  ValidationError,\n  DataError,\n  resolve,\n} from \"@showwhat/core\";\nimport type {\n  BuiltinCondition,\n  ConditionEvaluators,\n  Context,\n  ContextValue,\n  Definitions,\n  DefinitionReader,\n  Dependencies,\n  Resolution,\n  ResolutionError,\n  ResolverOptions,\n} from \"@showwhat/core\";\n\nexport * from \"@showwhat/core\";\n\nexport type ShowWhatOptions = ResolverOptions & {\n  data: DefinitionReader;\n};\n\nexport type Resolutions = Record<string, Resolution | ResolutionError>;\n\nasync function fetchDefinitions(data: DefinitionReader, keys?: string[]): Promise<Definitions> {\n  if (!keys) {\n    try {\n      return await data.getAll();\n    } catch (err) {\n      throw new DataError(\"Failed to fetch definitions\", err);\n    }\n  }\n\n  const definitions = {} as Record<string, Definitions[string] | null>;\n  await Promise.all(\n    keys.map(async (key) => {\n      try {\n        definitions[key] = await data.get(key);\n      } catch (err) {\n        throw new DataError(`Failed to fetch definition \"${key}\"`, err);\n      }\n    }),\n  );\n  return definitions as Definitions;\n}\n\nexport async function showwhat<\n  T extends Record<string, ContextValue> = Record<string, ContextValue>,\n  D extends Record<string, unknown> = Record<string, unknown>,\n>({\n  keys,\n  context,\n  deps,\n  options,\n}: {\n  keys?: string[];\n  context: Context<T>;\n  deps?: Dependencies<D>;\n  options: ShowWhatOptions;\n}): Promise<Resolutions> {\n  const contextResult = ContextSchema.safeParse(context);\n  if (!contextResult.success) {\n    throw new ValidationError(\n      contextResult.error.issues.map((i) => `[${i.path.join(\".\")}] ${i.message}`).join(\"; \"),\n      \"context\",\n    );\n  }\n\n  return resolve({\n    definitions: await fetchDefinitions(options.data, keys),\n    context: contextResult.data as Context<T>,\n    deps,\n    options: {\n      ...options,\n      evaluators: options.evaluators ?? builtinEvaluators,\n    },\n  });\n}\n\nconst COMPOSITE_TYPES = new Set([\"and\", \"or\"]);\n\nexport function registerEvaluators<T extends string>(\n  extra: ConditionEvaluators<T>,\n): ConditionEvaluators<BuiltinCondition[\"type\"] | T> {\n  for (const key of Object.keys(extra)) {\n    if (COMPOSITE_TYPES.has(key)) {\n      throw new Error(`Cannot register reserved condition type \"${key}\"`);\n    }\n  }\n  return { ...builtinEvaluators, ...extra };\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAcP,cAAc;AAQd,eAAe,iBAAiB,MAAwB,MAAuC;AAC7F,MAAI,CAAC,MAAM;AACT,QAAI;AACF,aAAO,MAAM,KAAK,OAAO;AAAA,IAC3B,SAAS,KAAK;AACZ,YAAM,IAAI,UAAU,+BAA+B,GAAG;AAAA,IACxD;AAAA,EACF;AAEA,QAAM,cAAc,CAAC;AACrB,QAAM,QAAQ;AAAA,IACZ,KAAK,IAAI,OAAO,QAAQ;AACtB,UAAI;AACF,oBAAY,GAAG,IAAI,MAAM,KAAK,IAAI,GAAG;AAAA,MACvC,SAAS,KAAK;AACZ,cAAM,IAAI,UAAU,+BAA+B,GAAG,KAAK,GAAG;AAAA,MAChE;AAAA,IACF,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,eAAsB,SAGpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKyB;AACvB,QAAM,gBAAgB,cAAc,UAAU,OAAO;AACrD,MAAI,CAAC,cAAc,SAAS;AAC1B,UAAM,IAAI;AAAA,MACR,cAAc,MAAM,OAAO,IAAI,CAAC,MAAM,IAAI,EAAE,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,IAAI;AAAA,MACrF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,QAAQ;AAAA,IACb,aAAa,MAAM,iBAAiB,QAAQ,MAAM,IAAI;AAAA,IACtD,SAAS,cAAc;AAAA,IACvB;AAAA,IACA,SAAS;AAAA,MACP,GAAG;AAAA,MACH,YAAY,QAAQ,cAAc;AAAA,IACpC;AAAA,EACF,CAAC;AACH;AAEA,IAAM,kBAAkB,oBAAI,IAAI,CAAC,OAAO,IAAI,CAAC;AAEtC,SAAS,mBACd,OACmD;AACnD,aAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,QAAI,gBAAgB,IAAI,GAAG,GAAG;AAC5B,YAAM,IAAI,MAAM,4CAA4C,GAAG,GAAG;AAAA,IACpE;AAAA,EACF;AACA,SAAO,EAAE,GAAG,mBAAmB,GAAG,MAAM;AAC1C;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  ContextSchema,\n  builtinEvaluators,\n  ValidationError,\n  DataError,\n  resolve,\n} from \"@showwhat/core\";\nimport type {\n  ConditionEvaluators,\n  Context,\n  Definitions,\n  DefinitionReader,\n  Dependencies,\n  Presets,\n  PresetReader,\n  Resolution,\n  ResolutionError,\n  ResolverOptions,\n} from \"@showwhat/core\";\n\nexport * from \"@showwhat/core\";\n\nexport type ShowWhatOptions = ResolverOptions & {\n  data: DefinitionReader;\n};\n\nexport type Resolutions = Record<string, Resolution | ResolutionError>;\n\nasync function fetchDefinitions(data: DefinitionReader, keys?: string[]): Promise<Definitions> {\n  if (!keys) {\n    try {\n      return await data.getAll();\n    } catch (err) {\n      throw new DataError(\"Failed to fetch definitions\", err);\n    }\n  }\n\n  const definitions = {} as Record<string, Definitions[string] | null>;\n  await Promise.all(\n    keys.map(async (key) => {\n      try {\n        definitions[key] = await data.get(key);\n      } catch (err) {\n        throw new DataError(`Failed to fetch definition \"${key}\"`, err);\n      }\n    }),\n  );\n  return definitions as Definitions;\n}\n\nexport async function showwhat({\n  keys,\n  context,\n  deps,\n  options,\n}: {\n  keys?: string[];\n  context: Context;\n  deps?: Dependencies;\n  options: ShowWhatOptions;\n}): Promise<Resolutions> {\n  const contextResult = ContextSchema.safeParse(context);\n  if (!contextResult.success) {\n    throw new ValidationError(\n      contextResult.error.issues.map((i) => `[${i.path.join(\".\")}] ${i.message}`).join(\"; \"),\n      \"context\",\n    );\n  }\n\n  return resolve({\n    definitions: await fetchDefinitions(options.data, keys),\n    context: contextResult.data as Context,\n    deps,\n    options: {\n      ...options,\n      evaluators: options.evaluators ?? builtinEvaluators,\n    },\n  });\n}\n\nexport async function mergePresets({\n  key,\n  presets,\n  overrides,\n}: {\n  key?: string;\n  presets?: PresetReader;\n  overrides?: Presets;\n}): Promise<Presets> {\n  if (!presets) {\n    return {\n      ...overrides,\n    };\n  }\n\n  const base = key ? await presets.getPresets(key) : await presets.getPresets();\n\n  return {\n    ...base,\n    ...overrides,\n  };\n}\n\nconst COMPOSITE_TYPES = new Set([\"and\", \"or\", \"checkAnnotations\"]);\n\nexport function registerEvaluators(extra: ConditionEvaluators): ConditionEvaluators {\n  for (const key of Object.keys(extra)) {\n    if (COMPOSITE_TYPES.has(key)) {\n      throw new Error(`Cannot register reserved condition type \"${key}\"`);\n    }\n  }\n  return { ...builtinEvaluators, ...extra };\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAcP,cAAc;AAQd,eAAe,iBAAiB,MAAwB,MAAuC;AAC7F,MAAI,CAAC,MAAM;AACT,QAAI;AACF,aAAO,MAAM,KAAK,OAAO;AAAA,IAC3B,SAAS,KAAK;AACZ,YAAM,IAAI,UAAU,+BAA+B,GAAG;AAAA,IACxD;AAAA,EACF;AAEA,QAAM,cAAc,CAAC;AACrB,QAAM,QAAQ;AAAA,IACZ,KAAK,IAAI,OAAO,QAAQ;AACtB,UAAI;AACF,oBAAY,GAAG,IAAI,MAAM,KAAK,IAAI,GAAG;AAAA,MACvC,SAAS,KAAK;AACZ,cAAM,IAAI,UAAU,+BAA+B,GAAG,KAAK,GAAG;AAAA,MAChE;AAAA,IACF,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAEA,eAAsB,SAAS;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAKyB;AACvB,QAAM,gBAAgB,cAAc,UAAU,OAAO;AACrD,MAAI,CAAC,cAAc,SAAS;AAC1B,UAAM,IAAI;AAAA,MACR,cAAc,MAAM,OAAO,IAAI,CAAC,MAAM,IAAI,EAAE,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,IAAI;AAAA,MACrF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,QAAQ;AAAA,IACb,aAAa,MAAM,iBAAiB,QAAQ,MAAM,IAAI;AAAA,IACtD,SAAS,cAAc;AAAA,IACvB;AAAA,IACA,SAAS;AAAA,MACP,GAAG;AAAA,MACH,YAAY,QAAQ,cAAc;AAAA,IACpC;AAAA,EACF,CAAC;AACH;AAEA,eAAsB,aAAa;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF,GAIqB;AACnB,MAAI,CAAC,SAAS;AACZ,WAAO;AAAA,MACL,GAAG;AAAA,IACL;AAAA,EACF;AAEA,QAAM,OAAO,MAAM,MAAM,QAAQ,WAAW,GAAG,IAAI,MAAM,QAAQ,WAAW;AAE5E,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,EACL;AACF;AAEA,IAAM,kBAAkB,oBAAI,IAAI,CAAC,OAAO,MAAM,kBAAkB,CAAC;AAE1D,SAAS,mBAAmB,OAAiD;AAClF,aAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,QAAI,gBAAgB,IAAI,GAAG,GAAG;AAC5B,YAAM,IAAI,MAAM,4CAA4C,GAAG,GAAG;AAAA,IACpE;AAAA,EACF;AACA,SAAO,EAAE,GAAG,mBAAmB,GAAG,MAAM;AAC1C;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showwhat",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A schema-based resolution engine for configuration and feature flags",
   "keywords": [
     "feature-flags",
@@ -41,14 +41,14 @@
     "dist"
   ],
   "dependencies": {
-    "@showwhat/core": "2.0.0"
+    "@showwhat/core": "2.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsup",