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

package/src/__tests__/branded.test.ts

@@ -8,7 +8,7 @@ import {
   nonEmptyString,
   positiveInt,
   shortId,
-  hashId,
+  deriveIdHash,
 } from '../branded';
 
 describe('branded', () => {
@@ -131,18 +131,18 @@ describe('branded', () => {
     });
   });
 
-  describe('hashId()', () => {
+  describe('deriveIdHash()', () => {
     test('returns a hex string', () => {
-      const id = hashId('test');
+      const id = deriveIdHash('test');
       expect(id).toMatch(/^[0-9a-f]{8}$/);
     });
 
     test('is deterministic', () => {
-      expect(hashId('hello')).toBe(hashId('hello'));
+      expect(deriveIdHash('hello')).toBe(deriveIdHash('hello'));
     });
 
     test('different inputs produce different outputs', () => {
-      expect(hashId('a')).not.toBe(hashId('b'));
+      expect(deriveIdHash('a')).not.toBe(deriveIdHash('b'));
     });
   });
 });

package/src/__tests__/context.test.ts

@@ -57,14 +57,14 @@ describe('createTrailContext', () => {
     expect(ctx.extensions?.['nested']).toEqual({ key: 'value' });
   });
 
-  test('provides a provision accessor backed by extensions', () => {
+  test('provides a resource accessor backed by extensions', () => {
     const widget = { id: 'widget-1' };
     const ctx = createTrailContext({
       extensions: { 'widget.main': widget },
     });
 
-    expect(ctx.provision('widget.main')).toBe(widget);
-    expect(ctx.provision<{ id: string }>({ id: 'widget.main' }).id).toBe(
+    expect(ctx.resource('widget.main')).toBe(widget);
+    expect(ctx.resource<{ id: string }>({ id: 'widget.main' }).id).toBe(
       'widget-1'
     );
   });

package/src/__tests__/contour.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import {
+  contour,
+  getContourIdMetadata,
+  getContourReferences,
+} from '../contour.js';
+
+const user = contour(
+  'user',
+  {
+    email: z.string().email(),
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  {
+    examples: [
+      {
+        email: 'ada@example.com',
+        id: '550e8400-e29b-41d4-a716-446655440000',
+        name: 'Ada',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+const gist = contour(
+  'gist',
+  {
+    id: z.string().uuid(),
+    ownerId: user.id(),
+    title: z.string(),
+  },
+  { identity: 'id' }
+);
+
+type UserId = z.infer<ReturnType<typeof user.id>>;
+type GistId = z.infer<ReturnType<typeof gist.id>>;
+
+const _ownerId: z.infer<typeof gist.shape.ownerId> = {} as UserId;
+// @ts-expect-error distinct contour ids should not be assignable
+const _mixedIds: UserId = {} as GistId;
+
+describe('contour()', () => {
+  describe('basics', () => {
+    test("returns kind 'contour'", () => {
+      expect(user.kind).toBe('contour');
+    });
+
+    test('preserves the contour name', () => {
+      expect(user.name).toBe('user');
+    });
+
+    test('preserves schema behavior', () => {
+      const parsed = user.safeParse({
+        email: 'ada@example.com',
+        id: '550e8400-e29b-41d4-a716-446655440000',
+        name: 'Ada',
+      });
+
+      expect(parsed.success).toBe(true);
+    });
+  });
+
+  describe('identity', () => {
+    test('stores the identity field name', () => {
+      expect(user.identity).toBe('id');
+    });
+
+    test('exposes the identity field schema', () => {
+      expect(user.identitySchema).toBe(user.shape.id);
+    });
+
+    test('returns a branded identity schema', () => {
+      const schema = user.id();
+      expect(
+        schema.safeParse('550e8400-e29b-41d4-a716-446655440000').success
+      ).toBe(true);
+      expect(schema).toBe(user.id());
+    });
+
+    test('attaches contour metadata to branded identity schemas', () => {
+      expect(getContourIdMetadata(user.id())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('preserves first-write metadata when identity schemas are shared', () => {
+      const baseUser = contour(
+        'user',
+        { id: z.string().uuid(), name: z.string() },
+        { identity: 'id' }
+      );
+      const admin = contour(
+        'admin',
+        { id: baseUser.shape.id, role: z.string() },
+        { identity: 'id' }
+      );
+
+      // The first contour to brand the schema wins — user, not admin.
+      expect(getContourIdMetadata(baseUser.id())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+      // admin still has its own id() accessor
+      expect(admin.id()).toBeDefined();
+
+      // Neither contour should emit its own identity as a cross-contour reference
+      expect(getContourReferences(baseUser)).toEqual([]);
+      expect(getContourReferences(admin)).toEqual([]);
+    });
+
+    test('rejects identity keys that are not in the shape', () => {
+      expect(() =>
+        contour(
+          'broken',
+          {
+            id: z.string(),
+          },
+          { identity: 'missing' as 'id' }
+        )
+      ).toThrow('identity "missing" must match a declared field');
+    });
+  });
+
+  describe('examples', () => {
+    test('stores examples as a frozen array', () => {
+      expect(user.examples).toHaveLength(1);
+      expect(Object.isFrozen(user.examples)).toBe(true);
+    });
+
+    test('validates examples against the contour schema', () => {
+      expect(() =>
+        contour(
+          'broken',
+          {
+            id: z.string().uuid(),
+            name: z.string(),
+          },
+          {
+            examples: [{ id: 'not-a-uuid', name: 42 as never }],
+            identity: 'id',
+          }
+        )
+      ).toThrow('example 0 is invalid');
+    });
+  });
+
+  describe('zod forwarding', () => {
+    test('supports .pick()', () => {
+      const schema = user.pick({ name: true });
+      expect(schema.safeParse({ name: 'Ada' }).success).toBe(true);
+      expect(schema.safeParse({ email: 'ada@example.com' }).success).toBe(
+        false
+      );
+    });
+
+    test('supports .extend()', () => {
+      const schema = user.extend({ active: z.boolean() });
+      expect(
+        schema.safeParse({
+          active: true,
+          email: 'ada@example.com',
+          id: '550e8400-e29b-41d4-a716-446655440000',
+          name: 'Ada',
+        }).success
+      ).toBe(true);
+    });
+
+    test('supports .array()', () => {
+      const schema = user.array();
+      expect(
+        schema.safeParse([
+          {
+            email: 'ada@example.com',
+            id: '550e8400-e29b-41d4-a716-446655440000',
+            name: 'Ada',
+          },
+        ]).success
+      ).toBe(true);
+    });
+
+    test('supports cross-contour references via .id()', () => {
+      expect(
+        gist.safeParse({
+          id: '0f31f6ba-6ff0-41ce-9f6b-8d132b6c4b81',
+          ownerId: '550e8400-e29b-41d4-a716-446655440000',
+          title: 'Hello',
+        }).success
+      ).toBe(true);
+      expect(getContourIdMetadata(gist.shape.ownerId)).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('lists declared contour references', () => {
+      expect(getContourReferences(gist)).toEqual([
+        {
+          contour: 'user',
+          field: 'ownerId',
+          identity: 'id',
+        },
+      ]);
+    });
+  });
+
+  describe('wrapper unwrapping', () => {
+    test('resolves .optional() contour id metadata', () => {
+      expect(getContourIdMetadata(user.id().optional())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves .nullable() contour id metadata', () => {
+      expect(getContourIdMetadata(user.id().nullable())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves .nullish() contour id metadata (two-level wrapper)', () => {
+      expect(getContourIdMetadata(user.id().nullish())).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('resolves deeply nested wrappers', () => {
+      expect(
+        getContourIdMetadata(user.id().nullable().optional().default(null))
+      ).toEqual({
+        contour: 'user',
+        identity: 'id',
+      });
+    });
+
+    test('detects references through .nullish() wrappers in contour shapes', () => {
+      const comment = contour(
+        'comment',
+        {
+          authorId: user.id().nullish(),
+          id: z.string().uuid(),
+          text: z.string(),
+        },
+        { identity: 'id' }
+      );
+
+      expect(getContourReferences(comment)).toEqual([
+        {
+          contour: 'user',
+          field: 'authorId',
+          identity: 'id',
+        },
+      ]);
+    });
+  });
+});