@ontrails/store 0.2.0

package/src/trails/reconcile.ts

@@ -0,0 +1,299 @@
+import { ConflictError, Result, ValidationError, trail } from '@ontrails/core';
+import type {
+  AnySignal,
+  Detour,
+  PermitRequirement,
+  Resource,
+  Trail,
+  TrailContext,
+  TrailExample,
+  TrailsError,
+} from '@ontrails/core';
+import { z } from 'zod';
+
+import type {
+  AnyStoreTable,
+  EntityOf,
+  StoreAccessor,
+  UpsertOf,
+} from '../types.js';
+import { versionFieldName } from '../store.js';
+import {
+  assertCurrentEntityOption,
+  createTableEntity,
+  mapStoreTrailError,
+} from './utils.js';
+import type { TableEntity } from './utils.js';
+
+type ReconcileConnection<TTable extends AnyStoreTable> = Readonly<
+  Record<TTable['name'], StoreAccessor<TTable>>
+>;
+
+export interface ReconcileConflict<TTable extends AnyStoreTable> {
+  readonly current: EntityOf<TTable>;
+  readonly incoming: UpsertOf<TTable>;
+}
+
+export type ReconcileStrategy<TTable extends AnyStoreTable> =
+  | 'last-write-wins'
+  | ((
+      conflict: ReconcileConflict<TTable>,
+      ctx: TrailContext
+    ) => Promise<UpsertOf<TTable>> | UpsertOf<TTable>);
+
+export interface ReconcileOptions<
+  TTable extends AnyStoreTable,
+  TConnection extends ReconcileConnection<TTable>,
+> {
+  /**
+   * Existing table entity to register on the reconcile trail. Pass the
+   * entity a `crud()` call over the same table exposes (its `entity`
+   * property) so `topo()` sees one shared instance instead of rejecting
+   * two same-named rebuilds as duplicates. When omitted, the factory
+   * builds its own.
+   */
+  readonly entity?: TableEntity<TTable>;
+  readonly description?: string;
+  readonly id?: string;
+  readonly on?: readonly (AnySignal | string)[];
+  /** Permit requirement declared on the reconcile trail. */
+  readonly permit?: PermitRequirement;
+  readonly resource: Resource<TConnection>;
+  readonly strategy?: ReconcileStrategy<TTable>;
+  readonly table: TTable;
+}
+
+const resolveAccessor = <
+  TTable extends AnyStoreTable,
+  TConnection extends ReconcileConnection<TTable>,
+>(
+  table: TTable,
+  resource: Resource<TConnection>,
+  ctx: TrailContext
+): StoreAccessor<TTable> => {
+  const connection = resource.from(ctx);
+  return connection[table.name as keyof TConnection] as StoreAccessor<TTable>;
+};
+
+const omitUndefined = <T extends Record<string, unknown>>(value: T): T =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, candidate]) => candidate !== undefined)
+  ) as T;
+
+const currentVersion = <TTable extends AnyStoreTable>(
+  current: EntityOf<TTable>
+): number => current[versionFieldName as keyof EntityOf<TTable>] as number;
+
+const lastWriteWins = <TTable extends AnyStoreTable>(
+  conflict: ReconcileConflict<TTable>
+): UpsertOf<TTable> =>
+  ({
+    ...conflict.current,
+    ...omitUndefined(conflict.incoming as Record<string, unknown>),
+    [versionFieldName]: currentVersion(conflict.current),
+  }) as UpsertOf<TTable>;
+
+const normalizeResolvedInput = <TTable extends AnyStoreTable>(
+  table: TTable,
+  current: EntityOf<TTable>,
+  resolved: UpsertOf<TTable>
+): UpsertOf<TTable> =>
+  ({
+    ...current,
+    ...omitUndefined(resolved as Record<string, unknown>),
+    [table.identity]: current[
+      table.identity as keyof EntityOf<TTable>
+    ] as EntityOf<TTable>[keyof EntityOf<TTable>],
+    [versionFieldName]: currentVersion(current),
+  }) as UpsertOf<TTable>;
+
+const deriveExamples = <TTable extends AnyStoreTable>(
+  table: TTable
+): readonly TrailExample<UpsertOf<TTable>, EntityOf<TTable>>[] | undefined => {
+  const examples = table.fixtures.flatMap((fixture) => {
+    const parsed = table.schema.safeParse(fixture);
+    if (!parsed.success) {
+      return [];
+    }
+
+    return [
+      {
+        expected: parsed.data as EntityOf<TTable>,
+        input: fixture as UpsertOf<TTable>,
+        name: `Reconcile ${table.name} ${String(
+          fixture[table.identity as keyof typeof fixture]
+        )}`,
+      },
+    ];
+  });
+
+  return examples.length === 0 ? undefined : Object.freeze(examples);
+};
+
+const buildConflict = async <TTable extends AnyStoreTable>(
+  table: TTable,
+  input: UpsertOf<TTable>,
+  accessor: StoreAccessor<TTable>,
+  error: ConflictError
+): Promise<ConflictError | ReconcileConflict<TTable>> => {
+  const identifier = input[table.identity as keyof typeof input] as
+    | EntityOf<TTable>[keyof EntityOf<TTable>]
+    | undefined;
+
+  if (identifier === undefined) {
+    return error;
+  }
+
+  const current = await accessor.get(identifier as never);
+  return current === null ? error : { current, incoming: input };
+};
+
+const resolveStrategy = async <TTable extends AnyStoreTable>(
+  strategy: ReconcileStrategy<TTable>,
+  conflict: ReconcileConflict<TTable>,
+  ctx: TrailContext
+): Promise<UpsertOf<TTable>> =>
+  strategy === 'last-write-wins'
+    ? lastWriteWins(conflict)
+    : await strategy(conflict, ctx);
+
+/** Resolve a version conflict through the configured strategy and retry the upsert. */
+const recoverConflict = async <TTable extends AnyStoreTable>(
+  table: TTable,
+  input: UpsertOf<TTable>,
+  accessor: StoreAccessor<TTable>,
+  error: ConflictError,
+  strategy: ReconcileStrategy<TTable>,
+  ctx: TrailContext
+) => {
+  const conflict = await buildConflict(table, input, accessor, error);
+  if (conflict instanceof ConflictError) {
+    return Result.err(conflict);
+  }
+
+  const resolved = await resolveStrategy(strategy, conflict, ctx);
+  const normalized = normalizeResolvedInput(table, conflict.current, resolved);
+  return Result.ok(await accessor.upsert(normalized));
+};
+
+/**
+ * Build the input schema for a reconcile trail.
+ *
+ * `fixtureSchema` makes generated fields (including `version` on versioned
+ * tables) optional because adapters populate them. Reconcile, however,
+ * relies on optimistic concurrency: the caller must pass the expected
+ * `version` so `assertExpectedVersionMatch` can detect stale payloads. We
+ * therefore extend `fixtureSchema` with a required `version` field so
+ * callers cannot sidestep optimistic concurrency at the input boundary.
+ */
+const buildReconcileInputSchema = <TTable extends AnyStoreTable>(
+  table: TTable
+): z.ZodType<UpsertOf<TTable>> =>
+  table.fixtureSchema.extend({
+    [versionFieldName]: z.number().int(),
+  }) as unknown as z.ZodType<UpsertOf<TTable>>;
+
+/** The implementation performs only the initial upsert; conflict recovery is handled by the detour. */
+const createReconcileImplementation =
+  <
+    TTable extends AnyStoreTable,
+    TConnection extends ReconcileConnection<TTable>,
+  >(
+    options: ReconcileOptions<TTable, TConnection>,
+    id: string
+  ) =>
+  async (input: UpsertOf<TTable>, ctx: TrailContext) => {
+    try {
+      const accessor = resolveAccessor(options.table, options.resource, ctx);
+      return Result.ok(await accessor.upsert(input));
+    } catch (error) {
+      if (error instanceof ConflictError) {
+        return Result.err(error);
+      }
+      return Result.err(mapStoreTrailError(id, error));
+    }
+  };
+
+/** Build the detour that handles ConflictError recovery via the configured strategy. */
+const createReconcileDetour = <
+  TTable extends AnyStoreTable,
+  TConnection extends ReconcileConnection<TTable>,
+>(
+  options: ReconcileOptions<TTable, TConnection>,
+  id: string,
+  strategy: ReconcileStrategy<TTable>
+): Detour<UpsertOf<TTable>, EntityOf<TTable>, TrailsError> => ({
+  maxAttempts: 1,
+  on: ConflictError,
+  recover: async (attempt, ctx) => {
+    const conflictError = attempt.error as ConflictError;
+    try {
+      const accessor = resolveAccessor(options.table, options.resource, ctx);
+      return await recoverConflict(
+        options.table,
+        attempt.input,
+        accessor,
+        conflictError,
+        strategy,
+        ctx
+      );
+    } catch (error) {
+      if (error instanceof ConflictError) {
+        return Result.err(error);
+      }
+      return Result.err(mapStoreTrailError(id, error) as TrailsError);
+    }
+  },
+});
+
+/**
+ * Produce one trail that retries a versioned upsert with a conflict strategy
+ * when the incoming entity is stale.
+ *
+ * Reconcile is bounded to a single retry via a declarative `detour`. If a
+ * concurrent writer races the retry and produces a second `ConflictError`,
+ * the detour loop wraps it in `RetryExhaustedError<ConflictError>` so
+ * callers can distinguish "retry reconcile at a higher level" from
+ * "reconcile tried and lost the race".
+ *
+ * @remarks
+ * For versioned tables, the derived input schema requires an explicit
+ * `version` field so callers cannot sidestep optimistic concurrency at the
+ * input boundary. `fixtureSchema` alone makes `version` optional because
+ * adapters populate it for writes; reconcile must reject that relaxed
+ * shape.
+ */
+export const reconcile = <
+  TTable extends AnyStoreTable,
+  TConnection extends ReconcileConnection<TTable>,
+>(
+  options: ReconcileOptions<TTable, TConnection>
+): Trail<UpsertOf<TTable>, EntityOf<TTable>> => {
+  assertCurrentEntityOption(options, 'reconcile() options');
+  if (!options.table.versioned) {
+    throw new ValidationError(
+      `reconcile("${options.table.name}") requires a versioned store table.`
+    );
+  }
+
+  const id = options.id ?? `${options.table.name}.reconcile`;
+  const tableEntity = options.entity ?? createTableEntity(options.table);
+  const strategy = options.strategy ?? 'last-write-wins';
+
+  return trail(id, {
+    description:
+      options.description ??
+      `Reconcile version conflicts for "${options.table.name}" entities.`,
+    detours: [createReconcileDetour(options, id, strategy)],
+    entities: [tableEntity],
+    examples: deriveExamples(options.table),
+    implementation: createReconcileImplementation(options, id),
+    input: buildReconcileInputSchema(options.table),
+    intent: 'write',
+    on: options.on,
+    output: options.table.schema as unknown as z.ZodType<EntityOf<TTable>>,
+    pattern: 'reconcile',
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
+    resources: [options.resource],
+  });
+};

package/src/trails/sync.ts

@@ -0,0 +1,274 @@
+import { InternalError, NotFoundError, Result, trail } from '@ontrails/core';
+import type {
+  AnySignal,
+  PermitRequirement,
+  Resource,
+  Trail,
+  TrailContext,
+  TrailExample,
+} from '@ontrails/core';
+import type { z } from 'zod';
+
+import type {
+  AnyStoreTable,
+  EntityOf,
+  ReadOnlyStoreTableAccessor,
+  StoreAccessor,
+  StoreIdentifierOf,
+  UpsertOf,
+} from '../types.js';
+import {
+  assertCurrentEntityOption,
+  createTableEntity,
+  mapStoreTrailError,
+} from './utils.js';
+import type { TableEntity } from './utils.js';
+
+type IdentityInputOf<TTable extends AnyStoreTable> = Readonly<
+  Record<Extract<TTable['identity'], string>, StoreIdentifierOf<TTable>>
+>;
+
+type SourceConnection<TTable extends AnyStoreTable> = Readonly<
+  Record<TTable['name'], ReadOnlyStoreTableAccessor<TTable>>
+>;
+
+type TargetConnection<TTable extends AnyStoreTable> = Readonly<
+  Record<TTable['name'], StoreAccessor<TTable>>
+>;
+
+export interface SyncEndpoint<
+  TTable extends AnyStoreTable,
+  TConnection extends SourceConnection<TTable> | TargetConnection<TTable>,
+> {
+  /**
+   * Existing table entity to register on the produced trail for this
+   * endpoint. Pass the entity a `crud()` bundle over the same table
+   * exposes (its `entity` property) so `topo()` sees one shared
+   * instance instead of rejecting two same-named rebuilds as
+   * duplicates. When omitted, the factory builds one from the table.
+   */
+  readonly entity?: TableEntity<TTable>;
+  readonly resource: Resource<TConnection>;
+  readonly table: TTable;
+}
+
+export type SyncTransform<
+  TSourceTable extends AnyStoreTable,
+  TTargetTable extends AnyStoreTable,
+> = (
+  entity: EntityOf<TSourceTable>,
+  ctx: TrailContext
+) => Promise<UpsertOf<TTargetTable>> | UpsertOf<TTargetTable>;
+
+export interface SyncOptions<
+  TSourceTable extends AnyStoreTable,
+  TTargetTable extends AnyStoreTable,
+  TSourceConnection extends SourceConnection<TSourceTable>,
+  TTargetConnection extends TargetConnection<TTargetTable>,
+> {
+  readonly description?: string;
+  readonly from: SyncEndpoint<TSourceTable, TSourceConnection>;
+  readonly id?: string;
+  readonly on?: readonly (AnySignal | string)[];
+  /**
+   * Permit requirement declared on the produced trail. Factory trails
+   * carry authored defaults like any hand-written trail.
+   */
+  readonly permit?: PermitRequirement;
+  readonly to: SyncEndpoint<TTargetTable, TTargetConnection>;
+  readonly transform?: SyncTransform<TSourceTable, TTargetTable>;
+}
+
+const resolveSourceAccessor = <
+  TTable extends AnyStoreTable,
+  TConnection extends SourceConnection<TTable>,
+>(
+  endpoint: SyncEndpoint<TTable, TConnection>,
+  ctx: TrailContext
+): ReadOnlyStoreTableAccessor<TTable> => {
+  const connection = endpoint.resource.from(ctx);
+  return connection[
+    endpoint.table.name as keyof TConnection
+  ] as ReadOnlyStoreTableAccessor<TTable>;
+};
+
+const resolveTargetAccessor = <
+  TTable extends AnyStoreTable,
+  TConnection extends TargetConnection<TTable>,
+>(
+  endpoint: SyncEndpoint<TTable, TConnection>,
+  ctx: TrailContext
+): StoreAccessor<TTable> => {
+  const connection = endpoint.resource.from(ctx);
+  return connection[
+    endpoint.table.name as keyof TConnection
+  ] as StoreAccessor<TTable>;
+};
+
+const sourceMissingError = <TTable extends AnyStoreTable>(
+  table: TTable,
+  id: StoreIdentifierOf<TTable>
+): NotFoundError =>
+  new NotFoundError(
+    `Store table "${table.name}" could not find source entity "${String(id)}"`
+  );
+
+const identityInputSchema = <TTable extends AnyStoreTable>(
+  table: TTable
+): z.ZodType<IdentityInputOf<TTable>> =>
+  table.schema.pick({
+    [table.identity]: true,
+  } as never) as unknown as z.ZodType<IdentityInputOf<TTable>>;
+
+const deriveExamples = <
+  TSourceTable extends AnyStoreTable,
+  TTargetTable extends AnyStoreTable,
+>(
+  sourceTable: TSourceTable,
+  targetTable: TTargetTable,
+  transform: SyncTransform<TSourceTable, TTargetTable> | undefined
+):
+  | readonly TrailExample<
+      IdentityInputOf<TSourceTable>,
+      EntityOf<TTargetTable>
+    >[]
+  | undefined => {
+  const targetById = new Map<
+    StoreIdentifierOf<TTargetTable>,
+    EntityOf<TTargetTable>
+  >();
+  for (const fixture of targetTable.fixtures) {
+    const id = fixture[targetTable.identity as keyof typeof fixture] as
+      | StoreIdentifierOf<TTargetTable>
+      | undefined;
+    if (id !== undefined) {
+      targetById.set(id, fixture as EntityOf<TTargetTable>);
+    }
+  }
+
+  const examples = sourceTable.fixtures.flatMap((fixture) => {
+    const id = fixture[sourceTable.identity as keyof typeof fixture] as
+      | StoreIdentifierOf<TSourceTable>
+      | undefined;
+    if (id === undefined) {
+      return [];
+    }
+
+    const targetFixture =
+      targetById.get(id as unknown as StoreIdentifierOf<TTargetTable>) ??
+      (transform === undefined && targetTable.schema.safeParse(fixture).success
+        ? (fixture as EntityOf<TTargetTable>)
+        : undefined);
+
+    if (targetFixture === undefined) {
+      return [];
+    }
+
+    return [
+      {
+        expected: targetFixture,
+        input: { [sourceTable.identity]: id } as IdentityInputOf<TSourceTable>,
+        name: `Sync ${targetTable.name} ${String(id)}`,
+      },
+    ];
+  });
+
+  return examples.length === 0 ? undefined : Object.freeze(examples);
+};
+
+/**
+ * Produce one trail that reads one source entity and writes the transformed
+ * result into a target store resource.
+ */
+export const sync = <
+  TSourceTable extends AnyStoreTable,
+  TTargetTable extends AnyStoreTable,
+  TSourceConnection extends SourceConnection<TSourceTable>,
+  TTargetConnection extends TargetConnection<TTargetTable>,
+>(
+  options: SyncOptions<
+    TSourceTable,
+    TTargetTable,
+    TSourceConnection,
+    TTargetConnection
+  >
+): Trail<IdentityInputOf<TSourceTable>, EntityOf<TTargetTable>> => {
+  assertCurrentEntityOption(options.from, 'sync() from options');
+  assertCurrentEntityOption(options.to, 'sync() to options');
+  const id = options.id ?? `${options.to.table.name}.sync`;
+  const sourceEntity =
+    options.from.entity ?? createTableEntity(options.from.table);
+  const targetEntity = options.to.entity ?? createTableEntity(options.to.table);
+
+  return trail(id, {
+    description:
+      options.description ??
+      `Sync one "${options.from.table.name}" entity into "${options.to.table.name}".`,
+    entities: [sourceEntity, targetEntity],
+    examples: deriveExamples(
+      options.from.table,
+      options.to.table,
+      options.transform
+    ) as
+      | readonly TrailExample<
+          IdentityInputOf<TSourceTable>,
+          EntityOf<TTargetTable>
+        >[]
+      | undefined,
+    // oxlint-disable-next-line max-statements -- sync implementation reads more clearly as one try/catch with schema validation, transform, and accessor call inline
+    implementation: async (input, ctx) => {
+      try {
+        const identifier = input[
+          options.from.table.identity as keyof typeof input
+        ] as StoreIdentifierOf<TSourceTable>;
+        const sourceRecord = await resolveSourceAccessor(options.from, ctx).get(
+          identifier
+        );
+
+        if (sourceRecord === null) {
+          return Result.err(sourceMissingError(options.from.table, identifier));
+        }
+
+        // No-transform path: the source entity is upserted directly into
+        // the target table. The generic signature does not require the two
+        // tables to be structurally compatible, so validate `next` against
+        // the target table's fixture schema at runtime. This catches
+        // accidentally omitted transforms before the underlying store sees
+        // a mismatched payload.
+        const next =
+          options.transform === undefined
+            ? options.to.table.fixtureSchema.safeParse(sourceRecord)
+            : undefined;
+
+        if (next !== undefined && !next.success) {
+          return Result.err(
+            new InternalError(
+              `${id} produced an invalid target entity: ${next.error.message}`
+            )
+          );
+        }
+
+        const payload =
+          options.transform === undefined
+            ? (next?.data as unknown as UpsertOf<TTargetTable>)
+            : await options.transform(sourceRecord, ctx);
+
+        const synced = await resolveTargetAccessor(options.to, ctx).upsert(
+          payload
+        );
+        return Result.ok(synced);
+      } catch (error) {
+        return Result.err(mapStoreTrailError(id, error));
+      }
+    },
+    input: identityInputSchema(options.from.table),
+    intent: 'write',
+    on: options.on,
+    output: options.to.table.schema as unknown as z.ZodType<
+      EntityOf<TTargetTable>
+    >,
+    pattern: 'sync',
+    ...(options.permit === undefined ? {} : { permit: options.permit }),
+    resources: [options.from.resource, options.to.resource],
+  });
+};

package/src/trails/utils.ts

@@ -0,0 +1,117 @@
+import {
+  InternalError,
+  ValidationError,
+  entity,
+  isTrailsError,
+} from '@ontrails/core';
+import type { Entity } from '@ontrails/core';
+import type { z } from 'zod';
+
+import type { AnyStoreTable } from '../types.js';
+
+/**
+ * The entity type produced by {@link createTableEntity} for a given store
+ * table. Threads the table's name, schema shape, and identity through the
+ * entity generics so downstream `deriveTrail()` calls derive concrete
+ * input/output types instead of widening back to
+ * `Entity<string, z.ZodRawShape, string>` (the `AnyEntity` alias).
+ */
+export type TableEntity<TTable extends AnyStoreTable> = Entity<
+  TTable['name'],
+  TTable['schema']['shape'],
+  Extract<TTable['identity'], keyof TTable['schema']['shape'] & string>
+>;
+
+/**
+ * Build the shape used when deriving an entity view of a store table.
+ *
+ * Entity validates every example against the shape passed in, so the shape
+ * must match how fixtures are actually shaped. Store fixtures may omit
+ * framework-generated fields (`createdAt`, `version`, ...) because the
+ * adapter populates them, so we mirror `fixtureSchema`'s treatment of
+ * generated fields: generated, non-identity fields are made optional; the
+ * identity field stays required because read/delete/update all derive their
+ * input from it. Previously reconcile.ts and sync.ts passed
+ * `table.schema.shape` directly and crashed when a fixture omitted
+ * `createdAt` or another generated field.
+ */
+export const buildEntityShape = (
+  table: AnyStoreTable
+): Record<string, z.ZodType> => {
+  const shape = table.schema.shape as unknown as Record<string, z.ZodType>;
+  const generatedNonIdentity = new Set(
+    table.generated.filter((field) => field !== table.identity)
+  );
+
+  if (generatedNonIdentity.size === 0) {
+    return shape;
+  }
+
+  const next: Record<string, z.ZodType> = {};
+  for (const [field, fieldSchema] of Object.entries(shape)) {
+    next[field] = generatedNonIdentity.has(field)
+      ? fieldSchema.optional()
+      : fieldSchema;
+  }
+  return next;
+};
+
+/**
+ * Derive an entity view of a store table.
+ *
+ * Both `sync` and `reconcile` use this helper so they pick up the
+ * fixture-shape treatment (generated fields optional).
+ *
+ * @remarks
+ * Intentionally not cached. `entity()` brands the identity schema via
+ * `Object.defineProperty(..., { writable: false })`, and re-invoking on a
+ * schema that's already been branded throws TypeError. Factory call sites
+ * already build the entity once per trail instance, so rebuilding on a
+ * warm call is cheap and side-effect-free.
+ */
+export const createTableEntity = <TTable extends AnyStoreTable>(
+  table: TTable
+): TableEntity<TTable> =>
+  entity(table.name, buildEntityShape(table), {
+    examples: table.fixtures as readonly Record<string, unknown>[],
+    identity: table.identity,
+  }) as TableEntity<TTable>;
+
+/** Reject the retired store-factory option instead of silently ignoring it. */
+export const assertCurrentEntityOption = (
+  value: unknown,
+  owner: string
+): void => {
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.hasOwn(value, 'contour')
+  ) {
+    throw new ValidationError(
+      `${owner} uses retired "contour"; use "entity" instead`
+    );
+  }
+};
+
+/**
+ * Coerce an unknown thrown value into an Error instance, preserving the
+ * original when possible.
+ */
+export const asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+/**
+ * Map a caught error into a `TrailsError` suitable for surfacing from a store
+ * trail factory. Pass-through for errors already in the taxonomy; otherwise
+ * wrap in an `InternalError` keyed by the trail id.
+ */
+export const mapStoreTrailError = (trailId: string, error: unknown): Error => {
+  if (isTrailsError(error)) {
+    return error;
+  }
+
+  const resolved = asError(error);
+  return new InternalError(`${trailId} failed: ${resolved.message}`, {
+    cause: resolved,
+  });
+};