showwhat 1.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,21 @@
 # showwhat
 
-Feature flag resolution engine — the main entry point for **showwhat**, a lightweight, extensible feature flag library.
+Schema and rule engine for **feature flags** and **config** resolution
+<br />Inspired by OpenAPI and Swagger
+
+## 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
 
@@ -16,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: {
@@ -26,25 +75,95 @@ const data = await MemoryData.fromObject({
     },
   },
 });
+```
+
+### 3. Resolve flags
+
+Pass a runtime **context** and the keys you want to resolve:
 
-const result = await showwhat({
-  key: "checkout_v2",
-  context: { env: "prod" },
+```ts
+import { showwhat } from "showwhat";
+
+const results = await showwhat({
+  keys: ["checkout_v2", "max_upload_size"],
+  context: { env: "prod", tier_level: 3 },
   options: { data },
 });
-console.log(result.value); // true
 ```
 
-## Features
+Omit `keys` to resolve all definitions at once.
 
-- `showwhat()` resolution engine with context validation
-- 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
+### 4. Use the results
 
-This package re-exports everything from `@showwhat/core`.
+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
+```
+
+### 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 @@ This package re-exports everything from `@showwhat/core`.
 - [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,14 +1,21 @@
-import { ResolverOptions, DefinitionReader, ConditionEvaluators, BuiltinCondition, Context, Resolution } 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;
 };
-declare function showwhat({ key, context, options, }: {
-    key: string;
+type Resolutions = Record<string, Resolution | ResolutionError>;
+declare function showwhat({ keys, context, deps, options, }: {
+    keys?: string[];
     context: Context;
+    deps?: Dependencies;
     options: ShowWhatOptions;
-}): Promise<Resolution>;
-declare function registerEvaluators<T extends string>(extra: ConditionEvaluators<T>): ConditionEvaluators<BuiltinCondition["type"] | T>;
+}): Promise<Resolutions>;
+declare function mergePresets({ key, presets, overrides, }: {
+    key?: string;
+    presets?: PresetReader;
+    overrides?: Presets;
+}): Promise<Presets>;
+declare function registerEvaluators(extra: ConditionEvaluators): ConditionEvaluators;
 
-export { type ShowWhatOptions, registerEvaluators, showwhat };
+export { type Resolutions, type ShowWhatOptions, mergePresets, registerEvaluators, showwhat };

package/dist/index.js

@@ -2,14 +2,35 @@
 import {
   ContextSchema,
   builtinEvaluators,
-  DefinitionNotFoundError,
   ValidationError,
+  DataError,
   resolve
 } from "@showwhat/core";
 export * from "@showwhat/core";
+async function fetchDefinitions(data, keys) {
+  if (!keys) {
+    try {
+      return await data.getAll();
+    } catch (err) {
+      throw new DataError("Failed to fetch definitions", err);
+    }
+  }
+  const definitions = {};
+  await Promise.all(
+    keys.map(async (key) => {
+      try {
+        definitions[key] = await data.get(key);
+      } catch (err) {
+        throw new DataError(`Failed to fetch definition "${key}"`, err);
+      }
+    })
+  );
+  return definitions;
+}
 async function showwhat({
-  key,
+  keys,
   context,
+  deps,
   options
 }) {
   const contextResult = ContextSchema.safeParse(context);
@@ -19,23 +40,33 @@ async function showwhat({
       "context"
     );
   }
-  const validatedContext = contextResult.data;
-  const def = await options.data.get(key);
-  if (!def) {
-    throw new DefinitionNotFoundError(key);
-  }
-  const result = await resolve({
-    definitions: { [key]: def },
-    context: validatedContext,
+  return resolve({
+    definitions: await fetchDefinitions(options.data, keys),
+    context: contextResult.data,
+    deps,
     options: {
-      evaluators: options.evaluators ?? builtinEvaluators,
-      fallback: options.fallback,
-      logger: options.logger
+      ...options,
+      evaluators: options.evaluators ?? builtinEvaluators
     }
   });
-  return result[key];
 }
-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)) {
@@ -45,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  DefinitionNotFoundError,\n  ValidationError,\n  resolve,\n} from \"@showwhat/core\";\nimport type {\n  BuiltinCondition,\n  ConditionEvaluators,\n  Context,\n  DefinitionReader,\n  Resolution,\n  ResolverOptions,\n} from \"@showwhat/core\";\n\nexport * from \"@showwhat/core\";\n\nexport type ShowWhatOptions = ResolverOptions & {\n  data: DefinitionReader;\n};\n\nexport async function showwhat({\n  key,\n  context,\n  options,\n}: {\n  key: string;\n  context: Context;\n  options: ShowWhatOptions;\n}): Promise<Resolution> {\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  const validatedContext = contextResult.data;\n  const def = await options.data.get(key);\n\n  if (!def) {\n    throw new DefinitionNotFoundError(key);\n  }\n\n  const result = await resolve({\n    definitions: { [key]: def },\n    context: validatedContext,\n    options: {\n      evaluators: options.evaluators ?? builtinEvaluators,\n      fallback: options.fallback,\n      logger: options.logger,\n    },\n  });\n\n  return result[key];\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;AAUP,cAAc;AAMd,eAAsB,SAAS;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF,GAIwB;AACtB,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,QAAM,mBAAmB,cAAc;AACvC,QAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,GAAG;AAEtC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,wBAAwB,GAAG;AAAA,EACvC;AAEA,QAAM,SAAS,MAAM,QAAQ;AAAA,IAC3B,aAAa,EAAE,CAAC,GAAG,GAAG,IAAI;AAAA,IAC1B,SAAS;AAAA,IACT,SAAS;AAAA,MACP,YAAY,QAAQ,cAAc;AAAA,MAClC,UAAU,QAAQ;AAAA,MAClB,QAAQ,QAAQ;AAAA,IAClB;AAAA,EACF,CAAC;AAED,SAAO,OAAO,GAAG;AACnB;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": "1.0.1",
+  "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": "1.0.1"
+    "@showwhat/core": "2.1.0"
   },
   "devDependencies": {
-    "@types/node": "^25.4.0",
-    "@vitest/coverage-v8": "^4.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.0",
-    "vitest": "^4.0.0"
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsup",