@ontrails/store 1.0.0-beta.14 → 1.0.0-beta.16

package/src/jsonfile/types.ts

@@ -0,0 +1,50 @@
+import type { Resource } from '@ontrails/core';
+import type {
+  AnyStoreDefinition,
+  AnyStoreTable,
+  StoreAccessor,
+  StoreAdapterOptions,
+} from '../types.js';
+
+/** Connection shape: one StoreAccessor per table name. */
+export type JsonFileConnection<TStore extends Record<string, AnyStoreTable>> =
+  Readonly<{ [K in keyof TStore]: StoreAccessor<TStore[K]> }>;
+
+/** Options for creating a jsonfile store. */
+export interface JsonFileStoreOptions<
+  TStore extends AnyStoreDefinition = AnyStoreDefinition,
+> extends StoreAdapterOptions<TStore> {
+  /** Directory where JSON files are written. One `<tableName>.json` per table. */
+  readonly dir: string;
+  /**
+   * Optional identity generator. Defaults to `Bun.randomUUIDv7()`.
+   *
+   * @remarks
+   * When a jsonfile table is reused across multiple `connectJsonFile` call
+   * sites (same `dir` + table), the runtime enforces that every connection
+   * supplies a compatible `generateIdentity`. That compatibility check is
+   * intentional reference equality, not a structural or behavioral comparison:
+   * two distinct arrow functions that happen to be "logically identical"
+   * (e.g. `() => uuid()` written inline in two files) will still be treated
+   * as a conflict and surface as a `ConflictError`. Callers that want to
+   * share a table across call sites should hoist `generateIdentity` to a
+   * stable reference — a module-level `const` or shared utility — and pass
+   * that same reference in from every connection, rather than recreating
+   * the function inline at each site.
+   *
+   * The conflict check only fires for custom generators. When no custom
+   * generator is provided for an auto-generated-identity store,
+   * `deriveTableReuseConfig` normalizes `generateIdentity` to `undefined`
+   * regardless of what (if anything) was passed, so two connections that
+   * both rely on defaults never conflict on this field. The same
+   * normalization also applies when the identity field is not in
+   * `generatedFields` — the generator is irrelevant in that case, so the
+   * check is skipped.
+   */
+  readonly generateIdentity?: () => string;
+}
+
+/** Resource type for a jsonfile store. */
+export type JsonFileStoreResource<
+  TStore extends Record<string, AnyStoreTable>,
+> = Resource<JsonFileConnection<TStore>>;

package/src/store.ts

@@ -1,8 +1,12 @@
-import { ValidationError } from '@ontrails/core';
-import type { z } from 'zod';
+import { stripDefaultsFromShape, ValidationError } from '@ontrails/core';
+import type { AnySignal } from '@ontrails/core';
+import { z } from 'zod';
 
+import { createStoreTableSignals } from './adapter-support.js';
 import type {
   StoreDefinition,
+  StoreKind,
+  StoreOptions,
   StoreObjectSchema,
   StoreTable,
   StoreTableInput,
@@ -12,14 +16,31 @@ import type {
 const isStoreObjectSchema = (schema: z.ZodType): schema is StoreObjectSchema =>
   schema.def.type === 'object' && 'shape' in schema.def;
 
+/**
+ * Name of the framework-managed version column used by versioned tables for
+ * optimistic concurrency control. Exported so adapters can gate their own
+ * version-handling logic without duplicating the literal.
+ */
+export const versionFieldName = 'version';
+const versionFieldSchema = z.number().int().positive();
+
 const uniqueStrings = <T extends string>(
   values: readonly T[] | undefined
 ): readonly T[] =>
   Object.freeze([...(values === undefined ? [] : new Set(values))]);
 
+const uniqueMergedStrings = <T extends string>(
+  ...groups: readonly (readonly T[] | undefined)[]
+): readonly T[] => uniqueStrings(groups.flatMap((group) => [...(group ?? [])]));
+
 const hasField = (schema: StoreObjectSchema, field: string): boolean =>
   Object.hasOwn(schema.shape, field);
 
+const versionedSchema = (schema: StoreObjectSchema): StoreObjectSchema =>
+  schema.extend({
+    [versionFieldName]: versionFieldSchema,
+  }) as StoreObjectSchema;
+
 const validateFieldList = (
   tableName: string,
   schema: StoreObjectSchema,
@@ -98,56 +119,16 @@ const deriveFixtureSchema = <TSchema extends StoreObjectSchema>(
   generated: readonly string[]
 ): StoreObjectSchema => partialFields(schema, generated);
 
-/**
- * Strip `default` wrappers from a Zod type so that partial update schemas
- * do not silently re-materialize defaults. Walks through all wrapper layers
- * (default, optional, nullable), strips defaults, and re-applies non-default
- * wrappers to preserve the nullable constraint.
- */
-const stripDefaultWrappers = (schema: z.ZodType): z.ZodType => {
-  const wrappers: ('optional' | 'nullable')[] = [];
-  let current = schema;
-
-  while (
-    current.def.type === 'default' ||
-    current.def.type === 'optional' ||
-    current.def.type === 'nullable'
-  ) {
-    const type = current.def.type as 'default' | 'optional' | 'nullable';
-    if (type !== 'default') {
-      wrappers.push(type);
-    }
-    current = (current.def as unknown as Record<string, unknown>)[
-      'innerType'
-    ] as z.ZodType;
-  }
-
-  // Re-apply nullable wrappers (optional is dropped — .partial() re-adds it)
-  return wrappers.includes('nullable') ? current.nullable() : current;
-};
-
-const stripDefaultsFromShape = (
-  schema: StoreObjectSchema
-): Record<string, z.ZodType> => {
-  const stripped: Record<string, z.ZodType> = {};
-
-  for (const [field, value] of Object.entries(schema.shape)) {
-    stripped[field] = stripDefaultWrappers(value);
-  }
-
-  return stripped;
-};
-
 const deriveUpdateSchema = (
   schema: StoreObjectSchema,
-  primaryKey: string
+  identity: string
 ): StoreObjectSchema => {
   const partial = schema
     .extend(stripDefaultsFromShape(schema))
     .partial() as StoreObjectSchema;
-  // Only omit the primaryKey if it's still present (it may already be in `generated`)
-  return hasField(partial, primaryKey)
-    ? omitFields(partial, [primaryKey])
+  // Only omit the identity field if it's still present (it may already be in `generated`)
+  return hasField(partial, identity)
+    ? omitFields(partial, [identity])
     : partial;
 };
 
@@ -156,13 +137,13 @@ const formatFixtureIssues = (issues: readonly { readonly message: string }[]) =>
 
 const validateFixturePrimaryKeys = (
   tableName: string,
-  primaryKey: string,
+  identity: string,
   fixtures: readonly Record<string, unknown>[]
 ): void => {
   const seen = new Set<unknown>();
 
   for (const [index, fixture] of fixtures.entries()) {
-    const identifier = fixture[primaryKey];
+    const identifier = fixture[identity];
     if (identifier === undefined) {
       continue;
     }
@@ -194,29 +175,81 @@ const normalizeReferences = (
 const validatePrimaryKey = (
   tableName: string,
   schema: StoreObjectSchema,
-  primaryKey: string
+  identity: string
 ): void => {
-  if (hasField(schema, primaryKey)) {
+  if (hasField(schema, identity)) {
     return;
   }
 
   throw new ValidationError(
-    `Store table "${tableName}" declares primaryKey "${primaryKey}" that is not present on the schema`
+    `Store table "${tableName}" declares identity "${identity}" that is not present on the schema`
+  );
+};
+
+const validateVersioning = (
+  tableName: string,
+  schema: StoreObjectSchema,
+  versioned: boolean
+): void => {
+  if (!versioned || !hasField(schema, versionFieldName)) {
+    return;
+  }
+
+  throw new ValidationError(
+    `Store table "${tableName}" cannot declare a "${versionFieldName}" field when versioned storage is enabled because the framework manages that field.`
+  );
+};
+
+const resolveStoreObjectSchema = (
+  tableName: string,
+  schema: StoreTableInput['schema']
+): StoreObjectSchema => {
+  if (isStoreObjectSchema(schema)) {
+    return schema;
+  }
+
+  throw new ValidationError(
+    `Store table "${tableName}" must use a Zod object schema`
   );
 };
 
+const resolveIdentity = (tableName: string, input: StoreTableInput): string => {
+  if (
+    input.identity !== undefined &&
+    input.primaryKey !== undefined &&
+    input.identity !== input.primaryKey
+  ) {
+    throw new ValidationError(
+      `Store table "${tableName}" declares conflicting identity "${input.identity}" and primaryKey "${input.primaryKey}"`
+    );
+  }
+
+  const identity = input.identity ?? input.primaryKey;
+  if (identity !== undefined) {
+    return identity;
+  }
+
+  throw new ValidationError(`Store table "${tableName}" must declare identity`);
+};
+
+const resolveIndexed = (input: StoreTableInput): readonly string[] =>
+  uniqueMergedStrings(input.indexed, input.indexes);
+
+const resolveVersioned = (input: StoreTableInput): boolean =>
+  input.versioned === true;
+
 const validateTableInput = (
   tableName: string,
   schema: StoreObjectSchema,
-  primaryKey: string,
+  identity: string,
   generated: readonly string[],
-  indexes: readonly string[],
+  indexed: readonly string[],
   references: Readonly<Partial<Record<string, string>>>,
   tableNames: readonly string[]
 ): void => {
-  validatePrimaryKey(tableName, schema, primaryKey);
+  validatePrimaryKey(tableName, schema, identity);
   validateFieldList(tableName, schema, generated, 'generated');
-  validateFieldList(tableName, schema, indexes, 'index');
+  validateFieldList(tableName, schema, indexed, 'indexed');
   validateReferences(tableName, schema, references, tableNames);
 };
 
@@ -224,144 +257,272 @@ type MutableTables<TTables extends StoreTablesInput> = {
   -readonly [TName in keyof TTables]: StoreDefinition<TTables>['tables'][TName];
 };
 
+const fixtureListFrom = (
+  fixtures: StoreTableInput['fixtures']
+): readonly unknown[] => (Array.isArray(fixtures) ? fixtures : []);
+
+const parseFixture = (
+  tableName: string,
+  fixtureSchema: StoreObjectSchema,
+  fixture: unknown,
+  index: number
+): Readonly<Record<string, unknown>> => {
+  const parsed = fixtureSchema.safeParse(fixture);
+  if (!parsed.success) {
+    throw new ValidationError(
+      `Store table "${tableName}" fixture ${index + 1} is invalid: ${formatFixtureIssues(parsed.error.issues)}`
+    );
+  }
+
+  return Object.freeze(parsed.data);
+};
+
 const normalizeFixtures = <TInput extends StoreTableInput>(
   tableName: string,
-  primaryKey: string,
+  identity: string,
   fixtureSchema: StoreObjectSchema,
   fixtures: TInput['fixtures']
 ): StoreTable<TInput>['fixtures'] => {
-  if (fixtures === undefined || fixtures.length === 0) {
+  const fixtureList = fixtureListFrom(fixtures);
+
+  if (fixtureList.length === 0) {
     return Object.freeze([]) as StoreTable<TInput>['fixtures'];
   }
 
-  const normalized = [];
+  const normalized: Record<string, unknown>[] = [];
 
-  for (const [index, fixture] of fixtures.entries()) {
-    const parsed = fixtureSchema.safeParse(fixture);
-    if (!parsed.success) {
-      throw new ValidationError(
-        `Store table "${tableName}" fixture ${index + 1} is invalid: ${formatFixtureIssues(parsed.error.issues)}`
-      );
-    }
-
-    normalized.push(Object.freeze(parsed.data));
+  for (const [index, fixture] of fixtureList.entries()) {
+    normalized.push(parseFixture(tableName, fixtureSchema, fixture, index));
   }
 
-  validateFixturePrimaryKeys(tableName, primaryKey, normalized);
+  validateFixturePrimaryKeys(tableName, identity, normalized);
   return Object.freeze(normalized) as StoreTable<TInput>['fixtures'];
 };
 
-const normalizeTable = <
+const resolveTableSchema = <TInput extends StoreTableInput<StoreObjectSchema>>(
+  tableName: string,
+  input: TInput
+): {
+  readonly schema: StoreObjectSchema;
+  readonly versioned: boolean;
+} => {
+  const authoredSchema = resolveStoreObjectSchema(tableName, input.schema);
+  const versioned = resolveVersioned(input);
+  validateVersioning(tableName, authoredSchema, versioned);
+
+  return {
+    schema: versioned ? versionedSchema(authoredSchema) : authoredSchema,
+    versioned,
+  };
+};
+
+const resolveGeneratedFields = <
+  TInput extends StoreTableInput<StoreObjectSchema>,
+>(
+  input: TInput,
+  versioned: boolean
+): readonly string[] =>
+  versioned
+    ? uniqueMergedStrings(input.generated, [versionFieldName])
+    : uniqueStrings(input.generated);
+
+const freezeNormalizedTable = <
   TName extends string,
   TInput extends StoreTableInput<StoreObjectSchema>,
 >(
   name: TName,
   input: TInput,
-  tableNames: readonly string[]
-): StoreTable<TInput, TName> => {
-  if (!isStoreObjectSchema(input.schema)) {
-    throw new ValidationError(
-      `Store table "${name}" must use a Zod object schema`
-    );
+  resolved: {
+    readonly fixtureSchema: StoreObjectSchema;
+    readonly fixtures: StoreTable<TInput>['fixtures'];
+    readonly generated: readonly string[];
+    readonly identity: string;
+    readonly indexed: readonly string[];
+    readonly insertSchema: StoreObjectSchema;
+    readonly references: Readonly<Partial<Record<string, string>>>;
+    readonly schema: StoreObjectSchema;
+    readonly signals: StoreTable<TInput, TName>['signals'];
+    readonly versioned: boolean;
   }
+): StoreTable<TInput, TName> =>
+  Object.freeze({
+    fixtureSchema: resolved.fixtureSchema,
+    fixtures: resolved.fixtures,
+    generated: resolved.generated,
+    identity: resolved.identity,
+    indexed: resolved.indexed,
+    indexes: resolved.indexed,
+    insertSchema: resolved.insertSchema,
+    name,
+    primaryKey: resolved.identity,
+    references: resolved.references,
+    schema: resolved.schema,
+    ...(input.search === undefined ? {} : { search: input.search }),
+    signals: resolved.signals,
+    updateSchema: deriveUpdateSchema(resolved.insertSchema, resolved.identity),
+    versioned: resolved.versioned,
+  }) as StoreTable<TInput, TName>;
 
-  const generated = uniqueStrings(input.generated);
-  const indexes = uniqueStrings(input.indexes);
+interface NormalizedTableState {
+  readonly generated: readonly string[];
+  readonly identity: string;
+  readonly indexed: readonly string[];
+  readonly references: Readonly<Partial<Record<string, string>>>;
+  readonly schema: StoreObjectSchema;
+  readonly versioned: boolean;
+}
+
+const resolveNormalizedTableState = <
+  TInput extends StoreTableInput<StoreObjectSchema>,
+>(
+  name: string,
+  input: TInput,
+  tableNames: readonly string[]
+): NormalizedTableState => {
+  const { schema, versioned } = resolveTableSchema(name, input);
+  const identity = resolveIdentity(name, input);
+  const generated = resolveGeneratedFields(input, versioned);
+  const indexed = resolveIndexed(input);
   const references = normalizeReferences(input.references);
+
   validateTableInput(
     name,
-    input.schema,
-    input.primaryKey,
+    schema,
+    identity,
     generated,
-    indexes,
+    indexed,
     references,
     tableNames
   );
 
-  const insertSchema = deriveInsertSchema(input.schema, generated);
-  const fixtureSchema = deriveFixtureSchema(input.schema, generated);
+  return {
+    generated,
+    identity,
+    indexed,
+    references,
+    schema,
+    versioned,
+  };
+};
+
+const resolveNormalizedTableArtifacts = <
+  TName extends string,
+  TInput extends StoreTableInput<StoreObjectSchema>,
+>(
+  name: TName,
+  input: TInput,
+  resolved: NormalizedTableState
+): {
+  readonly fixtureSchema: StoreObjectSchema;
+  readonly fixtures: StoreTable<TInput>['fixtures'];
+  readonly generated: readonly string[];
+  readonly identity: string;
+  readonly indexed: readonly string[];
+  readonly insertSchema: StoreObjectSchema;
+  readonly references: Readonly<Partial<Record<string, string>>>;
+  readonly schema: StoreObjectSchema;
+  readonly signals: StoreTable<TInput, TName>['signals'];
+} => {
+  const insertSchema = deriveInsertSchema(resolved.schema, resolved.generated);
+  const fixtureSchema = deriveFixtureSchema(
+    resolved.schema,
+    resolved.generated
+  );
   const fixtures = normalizeFixtures(
     name,
-    input.primaryKey,
+    resolved.identity,
     fixtureSchema,
     input.fixtures
   );
+  const signals = createStoreTableSignals(name, resolved.schema) as StoreTable<
+    TInput,
+    TName
+  >['signals'];
 
-  return Object.freeze({
+  return {
     fixtureSchema,
     fixtures,
-    generated,
-    indexes,
+    generated: resolved.generated,
+    identity: resolved.identity,
+    indexed: resolved.indexed,
     insertSchema,
-    name,
-    primaryKey: input.primaryKey,
-    references,
-    schema: input.schema,
-    ...(input.search === undefined ? {} : { search: input.search }),
-    updateSchema: deriveUpdateSchema(insertSchema, input.primaryKey),
-  }) as StoreTable<TInput, TName>;
+    references: resolved.references,
+    schema: resolved.schema,
+    signals,
+  };
+};
+
+const normalizeTable = <
+  TName extends string,
+  TInput extends StoreTableInput<StoreObjectSchema>,
+>(
+  name: TName,
+  input: TInput,
+  tableNames: readonly string[]
+): StoreTable<TInput, TName> => {
+  const resolved = resolveNormalizedTableState(name, input, tableNames);
+
+  return freezeNormalizedTable(name, input, {
+    ...resolveNormalizedTableArtifacts(name, input, resolved),
+    versioned: resolved.versioned,
+  });
+};
+
+const normalizeTables = <const TTables extends StoreTablesInput>(
+  tables: TTables,
+  tableNames: readonly Extract<keyof TTables, string>[]
+): MutableTables<TTables> => {
+  const normalized = {} as MutableTables<TTables>;
+
+  for (const name of tableNames) {
+    const input = tables[name];
+    if (input !== undefined) {
+      normalized[name] = normalizeTable(name, input, tableNames);
+    }
+  }
+
+  return normalized;
 };
 
+const collectStoreSignals = <const TTables extends StoreTablesInput>(
+  normalized: MutableTables<TTables>,
+  tableNames: readonly Extract<keyof TTables, string>[]
+): readonly AnySignal[] =>
+  Object.freeze(
+    tableNames.flatMap((name) => {
+      const table = normalized[name];
+      return table === undefined
+        ? []
+        : [table.signals.created, table.signals.updated, table.signals.removed];
+    })
+  );
+
 /**
- * Declare a connector-agnostic store definition from entity schemas and
+ * Declare a backend-agnostic store definition from entity schemas and
  * persistence metadata.
  *
- * The returned value is a normalized, read-only contract that connectors can
+ * The returned value is a normalized, read-only contract that adapters can
  * bind to a concrete runtime later.
  */
 export const store = <const TTables extends StoreTablesInput>(
-  tables: TTables
+  tables: TTables,
+  options: StoreOptions = {}
 ): StoreDefinition<TTables> => {
+  const kind: StoreKind = options.kind ?? 'tabular';
   const tableNames = Object.freeze(
     Object.keys(tables).toSorted()
   ) as readonly Extract<keyof TTables, string>[];
-
-  const normalized = {} as MutableTables<TTables>;
-  for (const name of tableNames) {
-    const input = tables[name];
-
-    if (input === undefined) {
-      continue;
-    }
-
-    normalized[name] = normalizeTable(name, input, tableNames);
-  }
-
+  const normalized = normalizeTables(tables, tableNames);
   const get = <TName extends Extract<keyof TTables, string>>(name: TName) =>
     normalized[name];
+  const signals = collectStoreSignals(normalized, tableNames);
 
   return Object.freeze({
     get,
-    kind: 'store' as const,
+    kind,
+    signals,
     tableNames,
     tables: Object.freeze(normalized),
+    type: 'store' as const,
   });
 };
-
-/**
- * Read the full entity schema from a normalized store table.
- */
-export const entitySchemaOf = <TTable extends StoreTable>(
-  table: TTable
-): TTable['schema'] => table.schema;
-
-/**
- * Read the fixture schema from a normalized store table.
- */
-export const fixtureSchemaOf = <TTable extends StoreTable>(
-  table: TTable
-): TTable['fixtureSchema'] => table.fixtureSchema;
-
-/**
- * Read the insert schema from a normalized store table.
- */
-export const insertSchemaOf = <TTable extends StoreTable>(
-  table: TTable
-): TTable['insertSchema'] => table.insertSchema;
-
-/**
- * Read the update schema from a normalized store table.
- */
-export const updateSchemaOf = <TTable extends StoreTable>(
-  table: TTable
-): TTable['updateSchema'] => table.updateSchema;