@ontrails/store 1.0.0-beta.14

package/dist/types.d.ts

@@ -0,0 +1,224 @@
+import type { z } from 'zod';
+/**
+ * Object schema accepted by the store definition layer.
+ */
+export type StoreObjectSchema = z.ZodObject<Record<string, z.ZodType>>;
+/**
+ * String field names available on a store-backed entity schema.
+ */
+export type StoreFieldKey<TSchema extends StoreObjectSchema> = Extract<keyof z.output<TSchema>, string>;
+type GeneratedFieldNames<TSchema extends StoreObjectSchema, TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined> = TGenerated extends readonly StoreFieldKey<TSchema>[] ? TGenerated[number] : never;
+/**
+ * Seed row accepted for one table fixture.
+ *
+ * Generated fields may be supplied explicitly, but they are optional so test
+ * fixtures can omit timestamps and similar server-managed values when the mock
+ * store can synthesize them.
+ */
+export type StoreFixtureInput<TSchema extends StoreObjectSchema, TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined = readonly StoreFieldKey<TSchema>[] | undefined> = Omit<z.input<TSchema>, Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>> & Partial<Pick<z.input<TSchema>, Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.input<TSchema>>>>;
+/**
+ * Normalized fixture row after schema validation and default application.
+ */
+export type StoreFixtureRow<TSchema extends StoreObjectSchema, TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined = readonly StoreFieldKey<TSchema>[] | undefined> = Omit<z.output<TSchema>, Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>> & Partial<Pick<z.output<TSchema>, Extract<GeneratedFieldNames<TSchema, TGenerated>, keyof z.output<TSchema>>>>;
+/**
+ * Connector-owned search metadata.
+ *
+ * The core package keeps this opaque on purpose. Search behavior is declared
+ * here and interpreted by a concrete connector later.
+ */
+export type StoreSearchDefinition = Readonly<Record<string, unknown>>;
+/**
+ * Authored metadata for one store table.
+ */
+export interface StoreTableInput<TSchema extends StoreObjectSchema = StoreObjectSchema, TGenerated extends readonly StoreFieldKey<TSchema>[] | undefined = readonly StoreFieldKey<TSchema>[] | undefined> {
+    readonly fixtures?: readonly StoreFixtureInput<TSchema, TGenerated>[];
+    readonly generated?: TGenerated;
+    readonly indexes?: readonly StoreFieldKey<TSchema>[];
+    readonly primaryKey: StoreFieldKey<TSchema>;
+    readonly references?: Readonly<Partial<Record<StoreFieldKey<TSchema>, string>>>;
+    readonly schema: TSchema;
+    readonly search?: StoreSearchDefinition;
+}
+/**
+ * Record of authored tables passed to `store(...)`.
+ */
+export type StoreTablesInput = Record<string, StoreTableInput<StoreObjectSchema, readonly StoreFieldKey<StoreObjectSchema>[] | undefined>>;
+/**
+ * Preserve generated fields when present, otherwise normalize to an empty tuple.
+ */
+export type GeneratedFieldsOfInput<TInput extends StoreTableInput> = TInput['generated'] extends readonly StoreFieldKey<TInput['schema']>[] ? TInput['generated'] : readonly [];
+/**
+ * Preserve index fields when present, otherwise normalize to an empty tuple.
+ */
+export type IndexFieldsOfInput<TInput extends StoreTableInput> = TInput['indexes'] extends readonly StoreFieldKey<TInput['schema']>[] ? TInput['indexes'] : readonly [];
+/**
+ * Preserve references when present, otherwise normalize to an empty object.
+ */
+export type ReferencesOfInput<TInput extends StoreTableInput> = TInput['references'] extends Readonly<Partial<Record<StoreFieldKey<TInput['schema']>, string>>> ? TInput['references'] : Readonly<Record<never, never>>;
+/**
+ * Preserve fixtures when present, otherwise normalize to an empty tuple.
+ */
+export type FixturesOfInput<TInput extends StoreTableInput> = TInput['fixtures'] extends readonly StoreFixtureInput<TInput['schema'], GeneratedFieldsOfInput<TInput>>[] ? readonly StoreFixtureRow<TInput['schema'], GeneratedFieldsOfInput<TInput>>[] : readonly [];
+/**
+ * Generated store table contract derived from authored metadata.
+ */
+export interface StoreTable<TInput extends StoreTableInput = StoreTableInput, TName extends string = string> {
+    readonly fixtureSchema: StoreObjectSchema;
+    readonly fixtures: FixturesOfInput<TInput>;
+    readonly generated: GeneratedFieldsOfInput<TInput>;
+    readonly indexes: IndexFieldsOfInput<TInput>;
+    readonly insertSchema: StoreObjectSchema;
+    readonly name: TName;
+    readonly primaryKey: TInput['primaryKey'];
+    readonly references: ReferencesOfInput<TInput>;
+    readonly schema: TInput['schema'];
+    readonly search?: TInput['search'];
+    readonly updateSchema: StoreObjectSchema;
+}
+/**
+ * Full store definition returned by `store(...)`.
+ */
+export interface StoreDefinition<TTables extends StoreTablesInput = StoreTablesInput> {
+    readonly get: <TName extends Extract<keyof TTables, string>>(name: TName) => StoreTable<TTables[TName], TName>;
+    readonly kind: 'store';
+    readonly tableNames: readonly Extract<keyof TTables, string>[];
+    readonly tables: {
+        readonly [TName in keyof TTables]: StoreTable<TTables[TName], Extract<TName, string>>;
+    };
+}
+/**
+ * Structural view of any normalized store table.
+ *
+ * This stays broad on purpose so connector packages can accept concrete store
+ * definitions returned by `store(...)` without erasing their table-specific
+ * types back to one canonical generic instantiation.
+ */
+export interface AnyStoreTable {
+    readonly fixtureSchema: StoreObjectSchema;
+    readonly fixtures: readonly Record<string, unknown>[];
+    readonly generated: readonly string[];
+    readonly indexes: readonly string[];
+    readonly insertSchema: StoreObjectSchema;
+    readonly name: string;
+    readonly primaryKey: string;
+    readonly references: Readonly<Partial<Record<string, string>>>;
+    readonly schema: StoreObjectSchema;
+    readonly search?: StoreSearchDefinition | undefined;
+    readonly updateSchema: StoreObjectSchema;
+}
+/**
+ * Structural view of any normalized store definition.
+ */
+export interface AnyStoreDefinition {
+    readonly kind: 'store';
+    readonly tableNames: readonly string[];
+    readonly tables: Readonly<Record<string, AnyStoreTable>>;
+}
+type GeneratedFieldKeysOf<TTable extends AnyStoreTable> = readonly Extract<TTable['generated'][number], StoreFieldKey<TTable['schema']>>[];
+/**
+ * Full entity type represented by one store table.
+ */
+export type EntityOf<TTable extends AnyStoreTable> = z.output<TTable['schema']>;
+/**
+ * Fixture seed input accepted for one table.
+ */
+export type FixtureInputOf<TTable extends AnyStoreTable> = StoreFixtureInput<TTable['schema'], GeneratedFieldKeysOf<TTable>>;
+/**
+ * Normalized fixture row available on one table.
+ */
+export type FixtureOf<TTable extends AnyStoreTable> = StoreFixtureRow<TTable['schema'], GeneratedFieldKeysOf<TTable>>;
+/**
+ * Primary-key field name for one store table.
+ */
+export type PrimaryKeyOf<TTable extends AnyStoreTable> = TTable['primaryKey'];
+/**
+ * Server-managed fields for one store table.
+ */
+export type GeneratedKeysOf<TTable extends AnyStoreTable> = Extract<TTable['generated'][number], StoreFieldKey<TTable['schema']>>;
+/**
+ * Insert shape: entity minus generated fields, with defaulted fields optional.
+ *
+ * Uses `z.input` so that fields with `.default()` are correctly represented as
+ * optional in the insert shape (matching the runtime insert schema behavior).
+ */
+export type InsertOf<TTable extends AnyStoreTable> = Omit<z.input<TTable['schema']>, GeneratedKeysOf<TTable>>;
+/**
+ * Update shape: partial insert minus the primary key (immutable identifier).
+ */
+export type UpdateOf<TTable extends AnyStoreTable> = Partial<Omit<InsertOf<TTable>, PrimaryKeyOf<TTable>>>;
+/**
+ * Typed filter shape for list operations.
+ */
+export type FiltersOf<TTable extends AnyStoreTable> = Partial<EntityOf<TTable>>;
+/**
+ * Common pagination controls for store list operations.
+ */
+export interface StoreListOptions {
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/**
+ * Shared identifier type for read/write accessors.
+ */
+export type StoreIdentifierOf<TTable extends AnyStoreTable> = EntityOf<TTable>[Extract<PrimaryKeyOf<TTable>, keyof EntityOf<TTable>>];
+/**
+ * Access mode for a bound store connection or provision.
+ */
+export type StoreAccessMode = 'readonly' | 'readwrite';
+/**
+ * Read-only table operations that every bound store must expose.
+ */
+export interface ReadOnlyStoreTableAccessor<TTable extends AnyStoreTable> {
+    /** Retrieve a single entity by primary key. Returns `null` when not found. */
+    get(id: StoreIdentifierOf<TTable>): Promise<EntityOf<TTable> | null>;
+    /**
+     * List entities, optionally filtered. Returns all rows when no filters are
+     * provided. Returns an empty array when no rows match.
+     */
+    list(filters?: FiltersOf<TTable>, options?: StoreListOptions): Promise<readonly EntityOf<TTable>[]>;
+}
+/**
+ * Writable table operations layered on top of the read contract.
+ */
+export interface StoreTableAccessor<TTable extends AnyStoreTable> extends ReadOnlyStoreTableAccessor<TTable> {
+    /**
+     * Insert a new entity.
+     *
+     * @throws {AlreadyExistsError} On primary key or unique constraint violation.
+     *
+     * @remarks
+     * This is an intentional throw-based boundary: store connectors throw typed
+     * errors (`AlreadyExistsError`) rather than returning `Result`. Trail
+     * implementations that call store accessors should catch and convert to
+     * `Result.err()` at their level. A future `safeInsert` returning `Result`
+     * is planned but deferred to avoid cascading changes across all connectors.
+     */
+    insert(input: InsertOf<TTable>): Promise<EntityOf<TTable>>;
+    /**
+     * Remove an entity by primary key. Returns `{ deleted: true }` when the
+     * row was found and removed, `{ deleted: false }` when no matching row
+     * existed (not an error).
+     */
+    remove(id: StoreIdentifierOf<TTable>): Promise<{
+        readonly deleted: boolean;
+    }>;
+    /**
+     * Patch an entity by primary key with partial fields. Returns the updated
+     * entity, or `null` when no row with that ID exists.
+     */
+    update(id: StoreIdentifierOf<TTable>, input: UpdateOf<TTable>): Promise<EntityOf<TTable> | null>;
+}
+/**
+ * Connection shape exposed by a read-only bound store.
+ */
+export type ReadOnlyStoreConnection<TStore extends AnyStoreDefinition> = {
+    readonly [TName in keyof TStore['tables']]: ReadOnlyStoreTableAccessor<TStore['tables'][TName]>;
+};
+/**
+ * Connection shape exposed by a writable bound store.
+ */
+export type StoreConnection<TStore extends AnyStoreDefinition> = {
+    readonly [TName in keyof TStore['tables']]: StoreTableAccessor<TStore['tables'][TName]>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ontrails/store",
+  "version": "1.0.0-beta.14",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./drizzle": "./src/drizzle/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^1.0.0-beta.13"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.3.5"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  }
+}

package/src/__tests__/store.test.ts

@@ -0,0 +1,333 @@
+import { describe, expect, test } from 'bun:test';
+import { ValidationError } from '@ontrails/core';
+import { z } from 'zod';
+
+import type {
+  EntityOf,
+  FixtureInputOf,
+  FixtureOf,
+  InsertOf,
+  UpdateOf,
+} from '../index.js';
+import {
+  entitySchemaOf,
+  fixtureSchemaOf,
+  insertSchemaOf,
+  store,
+  updateSchemaOf,
+} from '../index.js';
+
+const userSchema = z.object({
+  email: z.string().email(),
+  id: z.string(),
+});
+
+const gistSchema = z.object({
+  createdAt: z.string(),
+  description: z.string().nullable().default(null),
+  id: z.string(),
+  isPublic: z.boolean().default(true),
+  ownerId: z.string(),
+  tags: z.array(z.string()).default([]),
+  updatedAt: z.string(),
+});
+
+const createStoreDefinition = () =>
+  store({
+    gists: {
+      generated: ['id', 'createdAt', 'updatedAt'],
+      indexes: ['ownerId'],
+      primaryKey: 'id',
+      references: { ownerId: 'users' },
+      schema: gistSchema,
+      search: { fts: true },
+    },
+    users: {
+      generated: ['id'],
+      primaryKey: 'id',
+      schema: userSchema,
+    },
+  });
+
+const expectNormalizedGistTable = (
+  table: ReturnType<typeof createStoreDefinition>['tables']['gists']
+) => {
+  expect(table.name).toBe('gists');
+  expect(table.primaryKey).toBe('id');
+  expect(table.generated).toEqual(['id', 'createdAt', 'updatedAt']);
+  expect(table.indexes).toEqual(['ownerId']);
+  expect(table.references).toEqual({ ownerId: 'users' });
+  expect(table.search).toEqual({ fts: true });
+};
+
+const expectDerivedSchemas = (
+  table: ReturnType<typeof createStoreDefinition>['tables']['gists']
+) => {
+  expect(entitySchemaOf(table)).toBe(table.schema);
+  expect(fixtureSchemaOf(table)).toBe(table.fixtureSchema);
+  expect(insertSchemaOf(table)).toBe(table.insertSchema);
+  expect(updateSchemaOf(table)).toBe(table.updateSchema);
+
+  expect(
+    table.insertSchema.parse({
+      ownerId: 'user-1',
+    })
+  ).toEqual({
+    description: null,
+    isPublic: true,
+    ownerId: 'user-1',
+    tags: [],
+  });
+
+  expect(
+    table.updateSchema.parse({
+      description: 'Updated',
+    })
+  ).toEqual({
+    description: 'Updated',
+  });
+};
+
+const createTypeTestStore = () =>
+  store({
+    gists: {
+      generated: ['id', 'createdAt', 'updatedAt'],
+      primaryKey: 'id',
+      schema: gistSchema,
+    },
+  });
+
+const createGistEntity = <
+  TTable extends Parameters<typeof entitySchemaOf>[0],
+>() =>
+  ({
+    createdAt: '2026-04-03T12:00:00.000Z',
+    description: null,
+    id: 'gist-1',
+    isPublic: true,
+    ownerId: 'user-1',
+    tags: ['core'],
+    updatedAt: '2026-04-03T12:00:00.000Z',
+  }) as EntityOf<TTable>;
+
+const requireFixture = <T>(fixture: T | undefined): T => {
+  if (fixture === undefined) {
+    throw new Error('Expected fixture to be present');
+  }
+
+  return fixture;
+};
+
+describe('@ontrails/store', () => {
+  test('normalizes tables and derives insert/update schemas', () => {
+    const db = createStoreDefinition();
+
+    expect(db.kind).toBe('store');
+    expect(db.tableNames).toEqual(['gists', 'users']);
+
+    const table = db.tables.gists;
+    expectNormalizedGistTable(table);
+    expect(db.get('users')).toBe(db.tables.users);
+    expectDerivedSchemas(table);
+  });
+
+  test('normalizes fixtures through the derived fixture schema', () => {
+    const db = store({
+      gists: {
+        fixtures: [
+          {
+            id: 'gist-seed',
+            ownerId: 'user-1',
+          },
+        ],
+        generated: ['id', 'createdAt', 'updatedAt'],
+        primaryKey: 'id',
+        schema: gistSchema,
+      },
+    });
+
+    type GistTable = typeof db.tables.gists;
+
+    const fixtureInput: FixtureInputOf<GistTable> = {
+      id: 'gist-other',
+      ownerId: 'user-2',
+    };
+    const fixture: FixtureOf<GistTable> = requireFixture(
+      db.tables.gists.fixtures[0]
+    );
+
+    expect(fixtureInput.ownerId).toBe('user-2');
+    expect(fixture).toEqual({
+      description: null,
+      id: 'gist-seed',
+      isPublic: true,
+      ownerId: 'user-1',
+      tags: [],
+    });
+    expect(Object.isFrozen(fixture)).toBe(true);
+    expect(Object.isFrozen(db.tables.gists.fixtures)).toBe(true);
+    expect(db.tables.gists.fixtureSchema.parse({ ownerId: 'user-3' })).toEqual({
+      description: null,
+      isPublic: true,
+      ownerId: 'user-3',
+      tags: [],
+    });
+  });
+
+  test('rejects duplicate fixture primary keys when they are explicitly provided', () => {
+    expect(() =>
+      store({
+        gists: {
+          fixtures: [
+            {
+              id: 'gist-seed',
+              ownerId: 'user-1',
+            },
+            {
+              id: 'gist-seed',
+              ownerId: 'user-2',
+            },
+          ],
+          generated: ['id', 'createdAt', 'updatedAt'],
+          primaryKey: 'id',
+          schema: gistSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" fixture 2 duplicates primary key "gist-seed"'
+      )
+    );
+  });
+
+  test('rejects non-object schemas and unknown metadata fields', () => {
+    expect(() =>
+      store({
+        broken: {
+          primaryKey: 'id' as never,
+          schema: z.string() as never,
+        },
+      })
+    ).toThrow(
+      new ValidationError('Store table "broken" must use a Zod object schema')
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          primaryKey: 'slug' as never,
+          schema: gistSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" declares primaryKey "slug" that is not present on the schema'
+      )
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          generated: ['missing'] as const as never,
+          primaryKey: 'id',
+          schema: gistSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" declares generated field "missing" that is not present on the schema'
+      )
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          indexes: ['missing'] as const as never,
+          primaryKey: 'id',
+          schema: gistSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" declares index field "missing" that is not present on the schema'
+      )
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          fixtures: [{ id: 'gist-seed' } as never],
+          generated: ['id', 'createdAt', 'updatedAt'],
+          primaryKey: 'id',
+          schema: gistSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" fixture 1 is invalid: Invalid input: expected string, received undefined'
+      )
+    );
+  });
+
+  test('rejects bad references', () => {
+    expect(() =>
+      store({
+        gists: {
+          primaryKey: 'id',
+          references: { missing: 'users' } as never,
+          schema: gistSchema,
+        },
+        users: {
+          primaryKey: 'id',
+          schema: userSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" declares reference field "missing" that is not present on the schema'
+      )
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          primaryKey: 'id',
+          references: { ownerId: 'accounts' },
+          schema: gistSchema,
+        },
+        users: {
+          primaryKey: 'id',
+          schema: userSchema,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" references unknown table "accounts"'
+      )
+    );
+  });
+
+  test('type-level helpers expose connector-facing contracts', () => {
+    const db = createTypeTestStore();
+
+    type GistTable = typeof db.tables.gists;
+
+    const entity = createGistEntity<GistTable>();
+
+    const insert: InsertOf<GistTable> = {
+      description: null,
+      isPublic: true,
+      ownerId: 'user-1',
+      tags: ['core'],
+    };
+
+    const update: UpdateOf<GistTable> = {
+      description: 'Updated',
+    };
+
+    expect(insert.ownerId).toBe('user-1');
+    expect(update.description).toBe('Updated');
+    expect(entity.id).toBe('gist-1');
+    expect(db.tables.gists.name).toBe('gists');
+  });
+});