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

package/src/__tests__/store.test.ts

@@ -3,19 +3,15 @@ import { ValidationError } from '@ontrails/core';
 import { z } from 'zod';
 
 import type {
+  AnyStoreTable,
   EntityOf,
   FixtureInputOf,
   FixtureOf,
   InsertOf,
   UpdateOf,
 } from '../index.js';
-import {
-  entitySchemaOf,
-  fixtureSchemaOf,
-  insertSchemaOf,
-  store,
-  updateSchemaOf,
-} from '../index.js';
+import { store } from '../index.js';
+import { bindStoreDefinition } from '../internal/signal-identity.js';
 
 const userSchema = z.object({
   email: z.string().email(),
@@ -36,37 +32,64 @@ const createStoreDefinition = () =>
   store({
     gists: {
       generated: ['id', 'createdAt', 'updatedAt'],
-      indexes: ['ownerId'],
-      primaryKey: 'id',
+      identity: 'id',
+      indexed: ['ownerId'],
       references: { ownerId: 'users' },
       schema: gistSchema,
       search: { fts: true },
     },
     users: {
       generated: ['id'],
-      primaryKey: 'id',
+      identity: 'id',
       schema: userSchema,
     },
   });
 
+const expectGistSignals = (
+  table: ReturnType<typeof createStoreDefinition>['tables']['gists']
+) => {
+  expect(table.signals.created.id).toBe('gists.created');
+  expect(table.signals.updated.id).toBe('gists.updated');
+  expect(table.signals.removed.id).toBe('gists.removed');
+  expect(
+    table.signals.created.payload.parse({
+      createdAt: '2026-04-03T12:00:00.000Z',
+      id: 'gist-1',
+      ownerId: 'user-1',
+      updatedAt: '2026-04-03T12:00:00.000Z',
+    })
+  ).toEqual({
+    createdAt: '2026-04-03T12:00:00.000Z',
+    description: null,
+    id: 'gist-1',
+    isPublic: true,
+    ownerId: 'user-1',
+    tags: [],
+    updatedAt: '2026-04-03T12:00:00.000Z',
+  });
+};
+
 const expectNormalizedGistTable = (
   table: ReturnType<typeof createStoreDefinition>['tables']['gists']
 ) => {
   expect(table.name).toBe('gists');
+  expect(table.identity).toBe('id');
   expect(table.primaryKey).toBe('id');
   expect(table.generated).toEqual(['id', 'createdAt', 'updatedAt']);
+  expect(table.indexed).toEqual(['ownerId']);
   expect(table.indexes).toEqual(['ownerId']);
   expect(table.references).toEqual({ ownerId: 'users' });
   expect(table.search).toEqual({ fts: true });
+  expectGistSignals(table);
 };
 
 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.schema).toBeDefined();
+  expect(table.fixtureSchema).toBeDefined();
+  expect(table.insertSchema).toBeDefined();
+  expect(table.updateSchema).toBeDefined();
 
   expect(
     table.insertSchema.parse({
@@ -92,14 +115,26 @@ const createTypeTestStore = () =>
   store({
     gists: {
       generated: ['id', 'createdAt', 'updatedAt'],
-      primaryKey: 'id',
+      identity: 'id',
+      schema: gistSchema,
+    },
+  });
+
+const createVersionedStoreDefinition = () =>
+  store({
+    gists: {
+      generated: ['id', 'createdAt', 'updatedAt'],
+      identity: 'id',
       schema: gistSchema,
+      versioned: true,
     },
   });
 
-const createGistEntity = <
-  TTable extends Parameters<typeof entitySchemaOf>[0],
->() =>
+type VersionedGistTable = ReturnType<
+  typeof createVersionedStoreDefinition
+>['tables']['gists'];
+
+const createGistEntity = <TTable extends AnyStoreTable>() =>
   ({
     createdAt: '2026-04-03T12:00:00.000Z',
     description: null,
@@ -118,12 +153,66 @@ const requireFixture = <T>(fixture: T | undefined): T => {
   return fixture;
 };
 
+const createVersionedGistTypeSamples = (): {
+  readonly entity: EntityOf<VersionedGistTable>;
+  readonly fixtureInput: FixtureInputOf<VersionedGistTable>;
+  readonly insertInput: InsertOf<VersionedGistTable>;
+} => ({
+  entity: {
+    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',
+    version: 1,
+  },
+  fixtureInput: {
+    ownerId: 'user-2',
+    version: 2,
+  },
+  insertInput: {
+    ownerId: 'user-3',
+  },
+});
+
+const expectVersionedGistTypeSamples = ({
+  entity,
+  fixtureInput,
+  insertInput,
+}: ReturnType<typeof createVersionedGistTypeSamples>): void => {
+  expect(entity.version).toBe(1);
+  expect(fixtureInput.version).toBe(2);
+  expect(insertInput.ownerId).toBe('user-3');
+};
+
+const expectVersionedFixtureDefaults = (
+  db: ReturnType<typeof createVersionedStoreDefinition>
+): void => {
+  expect(db.tables.gists.fixtureSchema.parse({ ownerId: 'user-4' })).toEqual({
+    description: null,
+    isPublic: true,
+    ownerId: 'user-4',
+    tags: [],
+  });
+};
+
 describe('@ontrails/store', () => {
   test('normalizes tables and derives insert/update schemas', () => {
     const db = createStoreDefinition();
 
-    expect(db.kind).toBe('store');
+    expect(db.kind).toBe('tabular');
+    expect(db.signals.map((candidate) => candidate.id)).toEqual([
+      'gists.created',
+      'gists.updated',
+      'gists.removed',
+      'users.created',
+      'users.updated',
+      'users.removed',
+    ]);
     expect(db.tableNames).toEqual(['gists', 'users']);
+    expect(db.type).toBe('store');
 
     const table = db.tables.gists;
     expectNormalizedGistTable(table);
@@ -131,6 +220,21 @@ describe('@ontrails/store', () => {
     expectDerivedSchemas(table);
   });
 
+  test('accepts an explicit backend-agnostic kind', () => {
+    const db = store(
+      {
+        gists: {
+          identity: 'id',
+          schema: gistSchema,
+        },
+      },
+      { kind: 'document' }
+    );
+
+    expect(db.kind).toBe('document');
+    expect(db.tables.gists.identity).toBe('id');
+  });
+
   test('normalizes fixtures through the derived fixture schema', () => {
     const db = store({
       gists: {
@@ -141,7 +245,7 @@ describe('@ontrails/store', () => {
           },
         ],
         generated: ['id', 'createdAt', 'updatedAt'],
-        primaryKey: 'id',
+        identity: 'id',
         schema: gistSchema,
       },
     });
@@ -174,6 +278,42 @@ describe('@ontrails/store', () => {
     });
   });
 
+  test('normalizes versioned tables with a framework-managed version field', () => {
+    const db = createVersionedStoreDefinition();
+    const samples = createVersionedGistTypeSamples();
+
+    expect(db.tables.gists.versioned).toBe(true);
+    expect(db.tables.gists.generated).toEqual([
+      'id',
+      'createdAt',
+      'updatedAt',
+      'version',
+    ]);
+    expectVersionedGistTypeSamples(samples);
+    expect(db.tables.gists.schema.parse(samples.entity)).toEqual(
+      samples.entity
+    );
+    expect(
+      db.tables.gists.signals.updated.payload.parse({
+        createdAt: '2026-04-03T12:00:00.000Z',
+        id: 'gist-1',
+        ownerId: 'user-1',
+        updatedAt: '2026-04-03T12:00:00.000Z',
+        version: 2,
+      })
+    ).toEqual({
+      createdAt: '2026-04-03T12:00:00.000Z',
+      description: null,
+      id: 'gist-1',
+      isPublic: true,
+      ownerId: 'user-1',
+      tags: [],
+      updatedAt: '2026-04-03T12:00:00.000Z',
+      version: 2,
+    });
+    expectVersionedFixtureDefaults(db);
+  });
+
   test('rejects duplicate fixture primary keys when they are explicitly provided', () => {
     expect(() =>
       store({
@@ -189,7 +329,7 @@ describe('@ontrails/store', () => {
             },
           ],
           generated: ['id', 'createdAt', 'updatedAt'],
-          primaryKey: 'id',
+          identity: 'id',
           schema: gistSchema,
         },
       })
@@ -204,7 +344,7 @@ describe('@ontrails/store', () => {
     expect(() =>
       store({
         broken: {
-          primaryKey: 'id' as never,
+          identity: 'id' as never,
           schema: z.string() as never,
         },
       })
@@ -215,13 +355,13 @@ describe('@ontrails/store', () => {
     expect(() =>
       store({
         gists: {
-          primaryKey: 'slug' as never,
+          identity: 'slug' as never,
           schema: gistSchema,
         },
       })
     ).toThrow(
       new ValidationError(
-        'Store table "gists" declares primaryKey "slug" that is not present on the schema'
+        'Store table "gists" declares identity "slug" that is not present on the schema'
       )
     );
 
@@ -229,7 +369,7 @@ describe('@ontrails/store', () => {
       store({
         gists: {
           generated: ['missing'] as const as never,
-          primaryKey: 'id',
+          identity: 'id',
           schema: gistSchema,
         },
       })
@@ -242,14 +382,28 @@ describe('@ontrails/store', () => {
     expect(() =>
       store({
         gists: {
-          indexes: ['missing'] as const as never,
-          primaryKey: 'id',
+          identity: 'id',
+          schema: gistSchema.extend({ version: z.number().int() }),
+          versioned: true,
+        },
+      })
+    ).toThrow(
+      new ValidationError(
+        'Store table "gists" cannot declare a "version" field when versioned storage is enabled because the framework manages that field.'
+      )
+    );
+
+    expect(() =>
+      store({
+        gists: {
+          identity: 'id',
+          indexed: ['missing'] as const as never,
           schema: gistSchema,
         },
       })
     ).toThrow(
       new ValidationError(
-        'Store table "gists" declares index field "missing" that is not present on the schema'
+        'Store table "gists" declares indexed field "missing" that is not present on the schema'
       )
     );
 
@@ -258,7 +412,7 @@ describe('@ontrails/store', () => {
         gists: {
           fixtures: [{ id: 'gist-seed' } as never],
           generated: ['id', 'createdAt', 'updatedAt'],
-          primaryKey: 'id',
+          identity: 'id',
           schema: gistSchema,
         },
       })
@@ -273,12 +427,12 @@ describe('@ontrails/store', () => {
     expect(() =>
       store({
         gists: {
-          primaryKey: 'id',
+          identity: 'id',
           references: { missing: 'users' } as never,
           schema: gistSchema,
         },
         users: {
-          primaryKey: 'id',
+          identity: 'id',
           schema: userSchema,
         },
       })
@@ -291,12 +445,12 @@ describe('@ontrails/store', () => {
     expect(() =>
       store({
         gists: {
-          primaryKey: 'id',
+          identity: 'id',
           references: { ownerId: 'accounts' },
           schema: gistSchema,
         },
         users: {
-          primaryKey: 'id',
+          identity: 'id',
           schema: userSchema,
         },
       })
@@ -307,6 +461,23 @@ describe('@ontrails/store', () => {
     );
   });
 
+  test('keeps tabular aliases working for existing stores', () => {
+    const db = store({
+      gists: {
+        generated: ['id'],
+        indexes: ['ownerId'],
+        primaryKey: 'id',
+        schema: gistSchema,
+      },
+    });
+
+    expect(db.kind).toBe('tabular');
+    expect(db.tables.gists.identity).toBe('id');
+    expect(db.tables.gists.primaryKey).toBe('id');
+    expect(db.tables.gists.indexed).toEqual(['ownerId']);
+    expect(db.tables.gists.indexes).toEqual(['ownerId']);
+  });
+
   test('type-level helpers expose connector-facing contracts', () => {
     const db = createTypeTestStore();
 
@@ -331,3 +502,38 @@ describe('@ontrails/store', () => {
     expect(db.tables.gists.name).toBe('gists');
   });
 });
+
+describe('bindStoreDefinition', () => {
+  const definition = store({
+    gists: {
+      generated: ['id'],
+      identity: 'id',
+      schema: gistSchema,
+    },
+  });
+
+  test('rejects scopes containing ":"', () => {
+    expect(() => bindStoreDefinition(definition, 'bad:scope')).toThrow(
+      new ValidationError(
+        'Store resource id "bad:scope" is invalid: must be a non-empty string with no ":" characters and no whitespace.'
+      )
+    );
+  });
+
+  test('rejects scopes containing whitespace', () => {
+    expect(() => bindStoreDefinition(definition, 'bad scope')).toThrow(
+      ValidationError
+    );
+  });
+
+  test('rejects empty scopes', () => {
+    expect(() => bindStoreDefinition(definition, '')).toThrow(ValidationError);
+  });
+
+  test('accepts valid scopes and scopes store signal ids', () => {
+    const bound = bindStoreDefinition(definition, 'primary');
+    expect(bound.tables.gists.signals.created.id).toBe('primary:gists.created');
+    expect(bound.tables.gists.signals.updated.id).toBe('primary:gists.updated');
+    expect(bound.tables.gists.signals.removed.id).toBe('primary:gists.removed');
+  });
+});