@voyant-travel/core 0.109.0

package/dist/query.js

@@ -0,0 +1,126 @@
+/**
+ * Query Graph — cross-module reads that traverse {@link LinkDefinition}s.
+ *
+ * Modules expose {@link EntityFetcher}s for their entities. The graph
+ * planner fetches base records, walks link definitions for any dotted
+ * fields in the selection, issues parallel fetches for the linked
+ * entities, and stitches the results in-memory.
+ *
+ * This is an application-layer join, not a SQL join: modules never
+ * import one another's tables, and there are no database foreign keys
+ * between module schemas.
+ */
+/**
+ * Build a {@link QueryGraphContext} from plain records.
+ */
+export function createQueryContext(fetchers, links, linkService) {
+    return { fetchers: new Map(Object.entries(fetchers)), links, linkService };
+}
+/**
+ * Wrap a fixed {@link QueryGraphContext} in a callable runtime.
+ */
+export function createQueryRunner(ctx) {
+    return (config) => queryGraph(ctx, config);
+}
+function parseRelations(fields) {
+    const map = new Map();
+    for (const field of fields) {
+        const dotIdx = field.indexOf(".");
+        if (dotIdx === -1)
+            continue;
+        const relation = field.slice(0, dotIdx);
+        const subfield = field.slice(dotIdx + 1);
+        const existing = map.get(relation) ?? [];
+        existing.push(subfield);
+        map.set(relation, existing);
+    }
+    return Array.from(map.entries(), ([relation, subfields]) => ({ relation, subfields }));
+}
+function findLinkForRelation(links, entity, relation) {
+    for (const def of links) {
+        const leftEntity = def.left.linkable.entity;
+        const rightEntity = def.right.linkable.entity;
+        if (leftEntity === entity && rightEntity === relation) {
+            return { def, ourSideIsLeft: true };
+        }
+        if (rightEntity === entity && leftEntity === relation) {
+            return { def, ourSideIsLeft: false };
+        }
+    }
+    return undefined;
+}
+function unique(xs) {
+    return Array.from(new Set(xs));
+}
+/**
+ * Execute a cross-module read.
+ *
+ * @example
+ * ```ts
+ * const { data } = await queryGraph(ctx, {
+ *   entity: "person",
+ *   fields: ["id", "name", "product.*", "organization.name"],
+ *   filters: { country: "FR" },
+ *   pagination: { take: 50 },
+ * })
+ * // data[0].product === [{ id: "prod_...", ... }, ...]
+ * // data[0].organization === { id: "org_...", name: "..." } | null
+ * ```
+ */
+export async function queryGraph(ctx, config) {
+    const { fetchers, links, linkService } = ctx;
+    const { entity, fields, filters, pagination, context } = config;
+    const baseFetcher = fetchers.get(entity);
+    if (!baseFetcher) {
+        throw new Error(`queryGraph: no fetcher registered for entity "${entity}"`);
+    }
+    const plans = parseRelations(fields);
+    const baseRecords = await baseFetcher.list({ filters, pagination, context });
+    if (baseRecords.length === 0)
+        return { data: [] };
+    for (const { relation } of plans) {
+        const match = findLinkForRelation(links, entity, relation);
+        if (!match) {
+            throw new Error(`queryGraph: no link definition found for "${entity}.${relation}"`);
+        }
+        const { def, ourSideIsLeft } = match;
+        const targetSide = ourSideIsLeft ? def.right : def.left;
+        const targetEntity = targetSide.linkable.entity;
+        const targetIsList = targetSide.isList ?? false;
+        const targetFetcher = fetchers.get(targetEntity);
+        if (!targetFetcher) {
+            throw new Error(`queryGraph: no fetcher registered for target entity "${targetEntity}"`);
+        }
+        // ONE batched link lookup for all base records — per-base fan-out costs
+        // a query (and on Workers a subrequest) per record.
+        const baseIds = unique(baseRecords.map((r) => r.id));
+        const linkRows = await linkService.list(def.tableName, ourSideIsLeft ? { leftIds: baseIds } : { rightIds: baseIds });
+        // baseId → targetIds for stitching. Rows arrive in the link service's
+        // list order (created_at ASC), so per-base target order is preserved.
+        const idMap = new Map();
+        for (const baseId of baseIds)
+            idMap.set(baseId, []);
+        for (const row of linkRows) {
+            const baseId = ourSideIsLeft ? row.leftId : row.rightId;
+            const targetId = ourSideIsLeft ? row.rightId : row.leftId;
+            idMap.get(baseId)?.push(targetId);
+        }
+        // Hydrate all target records in one call.
+        const allTargetIds = unique(Array.from(idMap.values()).flat());
+        const targetRecords = allTargetIds.length > 0 ? await targetFetcher.list({ ids: allTargetIds, context }) : [];
+        const byTargetId = new Map(targetRecords.map((r) => [r.id, r]));
+        // Attach to each base record.
+        for (const record of baseRecords) {
+            const targetIds = idMap.get(record.id) ?? [];
+            const resolved = [];
+            for (const targetId of targetIds) {
+                const t = byTargetId.get(targetId);
+                if (t)
+                    resolved.push(t);
+            }
+            record[relation] = targetIsList ? resolved : (resolved[0] ?? null);
+        }
+    }
+    return { data: baseRecords };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+import type { Extension, Module } from "./module.js";
+export interface RegistryOptions {
+    modules?: Module[];
+    extensions?: Extension[];
+}
+/**
+ * Register module and extension hooks without binding to any specific
+ * transport framework.
+ *
+ * Transport adapters are expected to consume the returned modules and
+ * extensions separately.
+ */
+export declare function createRegistry(options?: RegistryOptions): {
+    modules: Module[];
+    extensions: Extension[];
+};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB;;;EAwB3D"}

package/dist/registry.js

@@ -0,0 +1,31 @@
+import { hooks } from "./hooks.js";
+/**
+ * Register module and extension hooks without binding to any specific
+ * transport framework.
+ *
+ * Transport adapters are expected to consume the returned modules and
+ * extensions separately.
+ */
+export function createRegistry(options = {}) {
+    const modules = options.modules ?? [];
+    const extensions = options.extensions ?? [];
+    for (const mod of modules) {
+        if (mod.hooks) {
+            for (const [event, handler] of Object.entries(mod.hooks)) {
+                hooks.on(event, handler);
+            }
+        }
+    }
+    for (const ext of extensions) {
+        if (ext.hooks) {
+            for (const [event, handler] of Object.entries(ext.hooks)) {
+                hooks.on(event, handler);
+            }
+        }
+    }
+    return {
+        modules,
+        extensions,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAQlC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,UAA2B,EAAE;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAA;IACrC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAA;IAE3C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO;QACP,UAAU;KACX,CAAA;AACH,CAAC"}

package/dist/workflows.d.ts

@@ -0,0 +1,140 @@
+import type { JobOptions, JobRunner } from "./orchestration.js";
+/**
+ * Runtime context passed to each step's run and compensate functions.
+ */
+export interface WorkflowContext {
+    /** Name of the workflow currently executing. */
+    workflowName: string;
+    /** JobRunner adapter — required when the workflow contains async steps. */
+    jobRunner?: JobRunner;
+    /**
+     * Accumulated results from prior steps, keyed by step name.
+     * Later steps may read outputs produced by earlier steps.
+     */
+    results: Record<string, unknown>;
+}
+/**
+ * Run function for a step. Receives the workflow input and context;
+ * returns the step's output (which is stored in `ctx.results`).
+ */
+export type StepRunFn<TInput = unknown, TOutput = unknown> = (input: TInput, ctx: WorkflowContext) => TOutput | Promise<TOutput>;
+/**
+ * Compensation function for a step. Invoked in reverse order on
+ * workflow failure. Receives the step's own output (what `run` returned).
+ */
+export type StepCompensateFn<TOutput = unknown> = (output: TOutput, ctx: WorkflowContext) => void | Promise<void>;
+/**
+ * Internal step definition accumulated by the {@link step} builder.
+ */
+export interface StepDefinition {
+    name: string;
+    runFn?: StepRunFn;
+    compensateFn?: StepCompensateFn;
+    isAsync: boolean;
+    jobOptions?: JobOptions;
+}
+/**
+ * Fluent builder for a workflow step. Chain `.run()`, optionally
+ * `.compensate()` and `.async()`.
+ */
+export interface StepBuilder<TInput = unknown, TOutput = unknown> {
+    /** Sets the step's run function. */
+    run(fn: StepRunFn<TInput, TOutput>): StepBuilder<TInput, TOutput>;
+    /** Sets the step's compensation (rollback) function. */
+    compensate(fn: StepCompensateFn<TOutput>): StepBuilder<TInput, TOutput>;
+    /**
+     * Marks the step as async: when reached, the workflow enqueues a job via
+     * the injected {@link JobRunner} and continues without blocking. The step
+     * name becomes the job name and the workflow input is the payload.
+     * Async steps do not participate in compensation.
+     */
+    async(options?: JobOptions): StepBuilder<TInput, TOutput>;
+    /** Internal definition. Do not mutate. */
+    readonly definition: StepDefinition;
+}
+/**
+ * Create a step builder. Name must be unique within a workflow.
+ *
+ * ```ts
+ * step<MyInput, MyOutput>("reserve-inventory")
+ *   .run(async (input, ctx) => {  ... })
+ *   .compensate(async (output, ctx) => {  ... })
+ * ```
+ */
+export declare function step<TInput = unknown, TOutput = unknown>(name: string): StepBuilder<TInput, TOutput>;
+/**
+ * Options passed to {@link WorkflowDefinition.run}.
+ */
+export interface WorkflowRunOptions {
+    /** Initial input passed to every step's run function. */
+    input?: unknown;
+    /** JobRunner — required when the workflow contains async steps. */
+    jobRunner?: JobRunner;
+    /**
+     * Pre-seeded `ctx.results` entries — used by resume runs to expose
+     * prior step outputs (from a parent run) without re-executing the
+     * step. Steps whose name appears in `seedResults` are skipped at
+     * the executor level: their entry is copied into ctx.results and
+     * `runFn` is not invoked. Compensation for skipped steps is also
+     * suppressed (the parent run's output remains canonical).
+     *
+     * Pairs with {@link skipUntil} — typically you set both to the
+     * same set so callers don't need to coordinate. When `skipUntil`
+     * is set, every step before that name MUST appear in `seedResults`
+     * so dependent steps see the values they expect.
+     */
+    seedResults?: Record<string, unknown>;
+    /**
+     * Resume sentinel — when set, the executor skips steps until it
+     * reaches this name (then runs normally from there onward). Steps
+     * before the sentinel are still added to ctx.results from
+     * {@link seedResults}. Throws if the named step doesn't exist in
+     * the workflow.
+     */
+    skipUntil?: string;
+}
+/**
+ * Result of a successful workflow execution.
+ */
+export interface WorkflowResult {
+    /** Step outputs keyed by step name. Async steps produce `{ jobId }`. */
+    results: Record<string, unknown>;
+}
+/**
+ * Workflow handle returned by {@link createWorkflow}.
+ */
+export interface WorkflowDefinition {
+    /** Workflow name. */
+    readonly name: string;
+    /** Ordered list of step builders. */
+    readonly steps: ReadonlyArray<StepBuilder>;
+    /** Execute the workflow. Throws on failure (after running compensations). */
+    run(options?: WorkflowRunOptions): Promise<WorkflowResult>;
+}
+/**
+ * Thrown when a workflow is misconfigured (e.g. missing run function,
+ * async step without a JobRunner, duplicate step names).
+ */
+export declare class WorkflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * Create an in-process workflow from a sequence of steps.
+ *
+ * Semantics:
+ * - Steps run sequentially in array order.
+ * - Each step's output is stored in `ctx.results[stepName]`.
+ * - If any step's run function throws, previously-completed steps'
+ *   compensation functions run in reverse order, then the error re-throws.
+ * - Compensation errors are caught and logged; they do not mask the
+ *   original failure.
+ * - Async steps (`.async()`) enqueue via the injected `JobRunner` using
+ *   the step name as the job name and the workflow input as the payload.
+ *   They do not block and do not participate in compensation.
+ *
+ * This is NOT a durable workflow engine — execution lives entirely within
+ * a single process. Durability for async work is delegated to the
+ * template's `JobRunner` implementation.
+ */
+export declare function createWorkflow(name: string, steps: ReadonlyArray<StepBuilder>): WorkflowDefinition;
+//# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"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"}

package/dist/workflows.js

@@ -0,0 +1,142 @@
+/**
+ * Create a step builder. Name must be unique within a workflow.
+ *
+ * ```ts
+ * step<MyInput, MyOutput>("reserve-inventory")
+ *   .run(async (input, ctx) => {  ... })
+ *   .compensate(async (output, ctx) => {  ... })
+ * ```
+ */
+export function step(name) {
+    const def = {
+        name,
+        isAsync: false,
+    };
+    const builder = {
+        run(fn) {
+            def.runFn = fn;
+            return builder;
+        },
+        compensate(fn) {
+            def.compensateFn = fn;
+            return builder;
+        },
+        async(options) {
+            def.isAsync = true;
+            if (options !== undefined)
+                def.jobOptions = options;
+            return builder;
+        },
+        definition: def,
+    };
+    return builder;
+}
+/**
+ * Thrown when a workflow is misconfigured (e.g. missing run function,
+ * async step without a JobRunner, duplicate step names).
+ */
+export class WorkflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowError";
+    }
+}
+/**
+ * Create an in-process workflow from a sequence of steps.
+ *
+ * Semantics:
+ * - Steps run sequentially in array order.
+ * - Each step's output is stored in `ctx.results[stepName]`.
+ * - If any step's run function throws, previously-completed steps'
+ *   compensation functions run in reverse order, then the error re-throws.
+ * - Compensation errors are caught and logged; they do not mask the
+ *   original failure.
+ * - Async steps (`.async()`) enqueue via the injected `JobRunner` using
+ *   the step name as the job name and the workflow input as the payload.
+ *   They do not block and do not participate in compensation.
+ *
+ * This is NOT a durable workflow engine — execution lives entirely within
+ * a single process. Durability for async work is delegated to the
+ * template's `JobRunner` implementation.
+ */
+export function createWorkflow(name, steps) {
+    const seen = new Set();
+    for (const builder of steps) {
+        const stepName = builder.definition.name;
+        if (seen.has(stepName)) {
+            throw new WorkflowError(`Workflow "${name}" has duplicate step name "${stepName}"`);
+        }
+        seen.add(stepName);
+    }
+    async function run(options = {}) {
+        const ctx = {
+            workflowName: name,
+            jobRunner: options.jobRunner,
+            results: { ...(options.seedResults ?? {}) },
+        };
+        const input = options.input;
+        const completed = [];
+        // Validate skipUntil up-front so callers get a clear error
+        // before any steps run (vs a silent no-op if the name is wrong).
+        if (options.skipUntil !== undefined) {
+            const found = steps.some((b) => b.definition.name === options.skipUntil);
+            if (!found) {
+                throw new WorkflowError(`Workflow "${name}" cannot resume: step "${options.skipUntil}" not found`);
+            }
+        }
+        let skipping = options.skipUntil !== undefined;
+        try {
+            for (const builder of steps) {
+                const def = builder.definition;
+                if (skipping) {
+                    if (def.name === options.skipUntil) {
+                        skipping = false;
+                    }
+                    else {
+                        // Step is skipped: keep its seeded result in ctx.results
+                        // (or null if none was seeded) and move on. Compensation
+                        // is suppressed for skipped steps — the parent run's
+                        // output is canonical, we shouldn't roll it back.
+                        continue;
+                    }
+                }
+                if (def.isAsync) {
+                    if (!ctx.jobRunner) {
+                        throw new WorkflowError(`Workflow "${name}" step "${def.name}" is async but no jobRunner was provided`);
+                    }
+                    const jobId = await ctx.jobRunner.enqueue(def.name, input, def.jobOptions);
+                    const output = { jobId };
+                    ctx.results[def.name] = output;
+                    continue;
+                }
+                if (!def.runFn) {
+                    throw new WorkflowError(`Workflow "${name}" step "${def.name}" has no run function`);
+                }
+                const output = await def.runFn(input, ctx);
+                ctx.results[def.name] = output;
+                completed.push({ def, output });
+            }
+            return { results: ctx.results };
+        }
+        catch (err) {
+            for (let i = completed.length - 1; i >= 0; i--) {
+                const entry = completed[i];
+                if (!entry?.def.compensateFn)
+                    continue;
+                try {
+                    await entry.def.compensateFn(entry.output, ctx);
+                }
+                catch (compensationErr) {
+                    console.error(`[workflow:${name}] compensation for step "${entry.def.name}" threw:`, compensationErr);
+                }
+            }
+            throw err;
+        }
+    }
+    return {
+        name,
+        steps,
+        run,
+    };
+}
+//# sourceMappingURL=workflows.js.map

package/dist/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@voyant-travel/core",
+  "version": "0.109.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "import": "./dist/env.js",
+      "default": "./dist/env.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js",
+      "default": "./dist/module.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js",
+      "default": "./dist/hooks.js"
+    },
+    "./locking": {
+      "types": "./dist/locking.d.ts",
+      "import": "./dist/locking.js",
+      "default": "./dist/locking.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "default": "./dist/registry.js"
+    },
+    "./container": {
+      "types": "./dist/container.d.ts",
+      "import": "./dist/container.js",
+      "default": "./dist/container.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js",
+      "default": "./dist/events.js"
+    },
+    "./orchestration": {
+      "types": "./dist/orchestration.d.ts",
+      "import": "./dist/orchestration.js",
+      "default": "./dist/orchestration.js"
+    },
+    "./links": {
+      "types": "./dist/links.d.ts",
+      "import": "./dist/links.js",
+      "default": "./dist/links.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "import": "./dist/query.js",
+      "default": "./dist/query.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows.d.ts",
+      "import": "./dist/workflows.js",
+      "default": "./dist/workflows.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "@voyant-travel/voyant-typescript-config": "^0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}