@showwhat/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gerald Yeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @showwhat/core
+
+> **Most users should install [`showwhat`](../showwhat) instead.** This package contains the low-level engine internals. The `showwhat` package re-exports everything from `@showwhat/core` and adds the main `showwhat()` entry point.
+
+Low-level condition engine and schemas for **showwhat** - a lightweight, extensible feature flag library.
+
+## Installation
+
+```bash
+npm install @showwhat/core
+```
+
+## Quick start
+
+```ts
+import { MemoryData, resolve, builtinEvaluators } from "@showwhat/core";
+
+const data = await MemoryData.fromObject({
+  definitions: {
+    checkout_v2: {
+      variations: [{ value: true, conditions: [{ type: "env", value: "prod" }] }, { value: false }],
+    },
+  },
+});
+
+const def = await data.get("checkout_v2");
+
+const result = await resolve({
+  definitions: { checkout_v2: def! },
+  context: { env: "prod" },
+  options: { evaluators: builtinEvaluators },
+});
+console.log(result.checkout_v2.value); // true
+```
+
+> **Note:** The resolver is strict — evaluators must be passed explicitly. There is no default evaluator set injected automatically.
+
+## Features
+
+- Built-in condition types: `string`, `number`, `datetime`, `bool`, `env`, `startAt`, `endAt`
+- Composite conditions with `and`/`or` logic
+- Custom condition types via `registerEvaluators()`
+- YAML and JSON parsing with schema validation
+- Pluggable data sources (`DefinitionReader` / `DefinitionWriter`)
+- Typed error hierarchy
+- Preset condition shortcuts
+
+## Documentation
+
+- [Quick Start](https://showwhat.yeojz.dev/docs/) — installation and first definition
+- [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`
+- [MemoryData](https://showwhat.yeojz.dev/docs/memory) — in-memory data source

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+import { ZodError, z } from 'zod';
+
+declare class ShowwhatError extends Error {
+    constructor(message: string);
+}
+declare class ParseError extends ShowwhatError {
+    readonly line?: number | undefined;
+    constructor(message: string, line?: number | undefined);
+}
+declare class ValidationError extends ShowwhatError {
+    readonly issues: ZodError["issues"];
+    constructor(message: string, context?: string);
+}
+declare class SchemaValidationError extends ValidationError {
+    constructor(zodError: ZodError, context?: string);
+}
+declare class DefinitionNotFoundError extends ShowwhatError {
+    readonly key: string;
+    constructor(key: string);
+}
+declare class DefinitionInactiveError extends ShowwhatError {
+    readonly key: string;
+    constructor(key: string);
+}
+declare class VariationNotFoundError extends ShowwhatError {
+    readonly key: string;
+    constructor(key: string);
+}
+declare class InvalidContextError extends ShowwhatError {
+    readonly key: string;
+    readonly value: string | number | boolean;
+    constructor(key: string, value: string | number | boolean);
+}
+declare class DataError extends ShowwhatError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+declare const PRIMITIVE_CONDITION_TYPES: {
+    readonly string: "string";
+    readonly number: "number";
+    readonly bool: "bool";
+    readonly datetime: "datetime";
+};
+type PrimitiveConditionType = (typeof PRIMITIVE_CONDITION_TYPES)[keyof typeof PRIMITIVE_CONDITION_TYPES];
+declare const CONDITION_TYPES: {
+    readonly env: "env";
+    readonly startAt: "startAt";
+    readonly endAt: "endAt";
+    readonly and: "and";
+    readonly or: "or";
+    readonly string: "string";
+    readonly number: "number";
+    readonly bool: "bool";
+    readonly datetime: "datetime";
+};
+declare const CONTEXT_KEYS: {
+    readonly env: "env";
+    readonly at: "at";
+};
+declare const StringConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"string">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        neq: "neq";
+        in: "in";
+        nin: "nin";
+        regex: "regex";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>;
+type StringCondition = z.infer<typeof StringConditionSchema>;
+declare const NumberConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"number">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        neq: "neq";
+        in: "in";
+        nin: "nin";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>;
+}, z.core.$strip>;
+type NumberCondition = z.infer<typeof NumberConditionSchema>;
+declare const DatetimeConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"datetime">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodISODateTime;
+}, z.core.$strip>;
+type DatetimeCondition = z.infer<typeof DatetimeConditionSchema>;
+declare const BoolConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"bool">;
+    key: z.ZodString;
+    op: z.ZodOptional<z.ZodLiteral<"eq">>;
+    value: z.ZodBoolean;
+}, z.core.$strip>;
+type BoolCondition = z.infer<typeof BoolConditionSchema>;
+declare const EnvConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"env">;
+    op: z.ZodOptional<z.ZodLiteral<"eq">>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>;
+type EnvCondition = z.infer<typeof EnvConditionSchema>;
+declare const StartAtConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"startAt">;
+    value: z.ZodISODateTime;
+}, z.core.$strip>;
+type StartAtCondition = z.infer<typeof StartAtConditionSchema>;
+declare const EndAtConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"endAt">;
+    value: z.ZodISODateTime;
+}, z.core.$strip>;
+type EndAtCondition = z.infer<typeof EndAtConditionSchema>;
+declare const BuiltinConditionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"string">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        neq: "neq";
+        in: "in";
+        nin: "nin";
+        regex: "regex";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"number">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        neq: "neq";
+        in: "in";
+        nin: "nin";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"datetime">;
+    key: z.ZodString;
+    op: z.ZodEnum<{
+        eq: "eq";
+        gt: "gt";
+        gte: "gte";
+        lt: "lt";
+        lte: "lte";
+    }>;
+    value: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"bool">;
+    key: z.ZodString;
+    op: z.ZodOptional<z.ZodLiteral<"eq">>;
+    value: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"env">;
+    op: z.ZodOptional<z.ZodLiteral<"eq">>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"startAt">;
+    value: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"endAt">;
+    value: z.ZodISODateTime;
+}, z.core.$strip>], "type">;
+type BuiltinCondition = z.infer<typeof BuiltinConditionSchema>;
+type Condition = BuiltinCondition | {
+    id?: string;
+    type: "and";
+    conditions: Condition[];
+} | {
+    id?: string;
+    type: "or";
+    conditions: Condition[];
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+declare const AndConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"and">;
+    conditions: z.ZodArray<z.ZodLazy<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+}, z.core.$strip>;
+declare const OrConditionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"or">;
+    conditions: z.ZodArray<z.ZodLazy<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+}, z.core.$strip>;
+declare const ConditionSchema: z.ZodType<Condition>;
+type AndCondition = z.infer<typeof AndConditionSchema>;
+type OrCondition = z.infer<typeof OrConditionSchema>;
+type CompositeCondition = AndCondition | OrCondition;
+declare function isAndCondition(c: Condition): c is AndCondition;
+declare function isOrCondition(c: Condition): c is OrCondition;
+
+declare const ContextSchema: z.ZodRecord<z.ZodString, z.ZodType<ContextValue, unknown, z.core.$ZodTypeInternals<ContextValue, unknown>>>;
+type ContextPrimitive = string | number | boolean;
+type ContextValue = ContextPrimitive | ContextPrimitive[] | {
+    [key: string]: ContextValue;
+};
+type Context = Record<string, ContextValue>;
+
+type VariationValue = unknown;
+declare const VariationValueSchema: z.ZodType<VariationValue>;
+declare const VariationSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    conditions: z.ZodOptional<z.ZodArray<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Variation = z.infer<typeof VariationSchema>;
+
+declare const DefinitionSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    variations: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Definition = z.infer<typeof DefinitionSchema>;
+declare const DefinitionsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    variations: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        conditions: z.ZodOptional<z.ZodArray<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+type Definitions = z.infer<typeof DefinitionsSchema>;
+declare const FileFormatSchema: z.ZodObject<{
+    definitions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+        variations: z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+            conditions: z.ZodOptional<z.ZodArray<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    presets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        key: z.ZodOptional<z.ZodString>;
+        defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strict>;
+type FileFormat = z.infer<typeof FileFormatSchema>;
+
+type PresetDefinition = {
+    type: string;
+    key?: string;
+    defaults?: Record<string, unknown>;
+};
+type Presets = Record<string, PresetDefinition>;
+declare const PRIMITIVE_TYPES: Set<string>;
+declare const PresetsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;
+
+declare const ResolutionSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    meta: z.ZodObject<{
+        context: z.ZodRecord<z.ZodString, z.ZodType<ContextValue, unknown, z.core.$ZodTypeInternals<ContextValue, unknown>>>;
+        variation: z.ZodObject<{
+            index: z.ZodNumber;
+            id: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            conditionCount: z.ZodNumber;
+        }, z.core.$strip>;
+        annotations: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Resolution = z.infer<typeof ResolutionSchema>;
+
+type Annotations = Record<string, unknown>;
+type ConditionEvaluatorArgs = {
+    condition: unknown;
+    context: Readonly<Context>;
+    annotations: Annotations;
+    depth: string;
+};
+type ConditionEvaluator = (args: ConditionEvaluatorArgs) => Promise<boolean>;
+type ConditionEvaluators<T extends string = string> = Record<T, ConditionEvaluator>;
+declare const noConditionEvaluator: ConditionEvaluator;
+
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+declare const noopLogger: Logger;
+
+type EvaluateConditionArgs = {
+    condition: Condition;
+    context: Readonly<Context>;
+    evaluators: ConditionEvaluators;
+    annotations: Annotations;
+    depth?: string;
+    logger?: Logger;
+    fallback?: ConditionEvaluator;
+};
+declare function evaluateCondition({ condition, context, evaluators, annotations, depth, logger, fallback, }: EvaluateConditionArgs): Promise<boolean>;
+
+declare const builtinEvaluators: ConditionEvaluators<BuiltinCondition["type"]>;
+
+type ResolverOptions = {
+    evaluators?: ConditionEvaluators;
+    fallback?: ConditionEvaluator;
+    logger?: Logger;
+};
+declare function resolveVariation({ variations, context, options, }: {
+    variations: Variation[];
+    context: Readonly<Context>;
+    options?: ResolverOptions;
+}): Promise<{
+    variation: Variation;
+    variationIndex: number;
+    annotations: Annotations;
+} | null>;
+/**
+ * Resolve all definitions against the given context.
+ *
+ * Uses `Promise.all` — if any single key fails (not found, inactive, no match),
+ * the entire call rejects. Callers who need partial results should resolve
+ * keys individually via `resolveVariation`.
+ */
+declare function resolve({ definitions, context, options, }: {
+    definitions: Definitions;
+    context: Readonly<Context>;
+    options?: ResolverOptions;
+}): Promise<Record<string, Resolution>>;
+
+interface DefinitionReader {
+    get(key: string): Promise<Definition | null>;
+    getAll(): Promise<Definitions>;
+    load?(): Promise<void>;
+    close?(): Promise<void>;
+    ping?(): Promise<void>;
+}
+interface DefinitionWriter {
+    put(key: string, definition: Definition): Promise<void>;
+    delete(key: string): Promise<void>;
+    putMany(flags: Definitions, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    listKeys(): Promise<string[]>;
+    load?(): Promise<void>;
+    close?(): Promise<void>;
+    ping?(): Promise<void>;
+}
+interface DefinitionData extends DefinitionReader, DefinitionWriter {
+}
+interface PresetReader {
+    getPresets(): Promise<Presets>;
+    getPresets(key: string): Promise<Presets>;
+}
+declare function isWritable(reader: DefinitionReader): reader is DefinitionData;
+declare class MemoryData implements DefinitionReader, PresetReader {
+    #private;
+    private constructor();
+    static fromObject(raw: unknown): Promise<MemoryData>;
+    static fromYaml(yaml: string): Promise<MemoryData>;
+    get(key: string): Promise<Definition | null>;
+    getAll(): Promise<Definitions>;
+    getPresets(): Promise<Presets>;
+}
+
+declare function parseYaml(input: string): Promise<FileFormat>;
+declare function parseObject(raw: unknown): Promise<FileFormat>;
+declare function parsePresetsObject(raw: unknown): Promise<Presets>;
+declare function parsePresetsYaml(input: string): Promise<Presets>;
+
+declare function createPresetConditions(presets: Presets): ConditionEvaluators;
+
+export { type AndCondition, type Annotations, type BoolCondition, BoolConditionSchema, type BuiltinCondition, BuiltinConditionSchema, CONDITION_TYPES, CONTEXT_KEYS, type CompositeCondition, type Condition, type ConditionEvaluator, type ConditionEvaluatorArgs, type ConditionEvaluators, ConditionSchema, type Context, ContextSchema, type ContextValue, DataError, type DatetimeCondition, DatetimeConditionSchema, type Definition, type DefinitionData, DefinitionInactiveError, DefinitionNotFoundError, type DefinitionReader, DefinitionSchema, type DefinitionWriter, type Definitions, DefinitionsSchema, type EndAtCondition, EndAtConditionSchema, type EnvCondition, EnvConditionSchema, type EvaluateConditionArgs, type FileFormat, FileFormatSchema, InvalidContextError, type Logger, MemoryData, type NumberCondition, NumberConditionSchema, type OrCondition, PRIMITIVE_CONDITION_TYPES, PRIMITIVE_TYPES, ParseError, type PresetDefinition, type PresetReader, type Presets, PresetsSchema, type PrimitiveConditionType, type Resolution, ResolutionSchema, type ResolverOptions, SchemaValidationError, ShowwhatError, type StartAtCondition, StartAtConditionSchema, type StringCondition, StringConditionSchema, ValidationError, type Variation, VariationNotFoundError, VariationSchema, type VariationValue, VariationValueSchema, builtinEvaluators, createPresetConditions, evaluateCondition, isAndCondition, isOrCondition, isWritable, noConditionEvaluator, noopLogger, parseObject, parsePresetsObject, parsePresetsYaml, parseYaml, resolve, resolveVariation };