@epsilon-asi/foundation 0.0.1-testing

package/src/decorators/factory/__tests__/cloneAndSnapshot.test.ts

@@ -0,0 +1,223 @@
+import { cloneDeep, deepFreeze, immutableClone } from '../clone';
+import { createSnapshot } from '../snapshot';
+import type { DecorationRecord } from '../types';
+
+describe('clone and freeze helpers', () => {
+  it('returns primitive values and functions without cloning them', () => {
+    const fn = () => 'ok';
+
+    expect(cloneDeep(undefined)).toBeUndefined();
+    expect(cloneDeep(null)).toBeNull();
+    expect(cloneDeep(123)).toBe(123);
+    expect(cloneDeep('value')).toBe('value');
+    expect(cloneDeep(fn)).toBe(fn);
+  });
+
+  it('deep-clones dates, regexes, arrays, maps, sets, symbols, descriptors, prototypes, and circular references', () => {
+    const symbolKey = Symbol('secret');
+    const prototype = { inherited: true };
+    const source = Object.create(prototype) as {
+      date: Date;
+      regex: RegExp;
+      list: Array<{ value: string }>;
+      map: Map<{ key: string }, { value: string }>;
+      set: Set<{ value: string }>;
+      self?: unknown;
+      computed: string;
+      [symbolKey]: { nested: string };
+    };
+
+    const mapKey = { key: 'map-key' };
+    const mapValue = { value: 'map-value' };
+    const setValue = { value: 'set-value' };
+
+    source.date = new Date('2024-01-01T00:00:00.000Z');
+    source.regex = /users/gi;
+    source.list = [{ value: 'list-value' }];
+    source.map = new Map([[mapKey, mapValue]]);
+    source.set = new Set([setValue]);
+    source[symbolKey] = { nested: 'symbol-value' };
+    source.self = source;
+    Object.defineProperty(source, 'computed', {
+      enumerable: true,
+      get() {
+        return 'computed-value';
+      },
+    });
+
+    const cloned = cloneDeep(source);
+
+    expect(Object.getPrototypeOf(cloned)).toBe(prototype);
+    expect(cloned).not.toBe(source);
+    expect(cloned.date).not.toBe(source.date);
+    expect(cloned.date.getTime()).toBe(source.date.getTime());
+    expect(cloned.regex).not.toBe(source.regex);
+    expect(cloned.regex.source).toBe('users');
+    expect(cloned.regex.flags).toContain('g');
+    expect(cloned.regex.flags).toContain('i');
+    expect(cloned.list).not.toBe(source.list);
+    expect(cloned.list[0]).not.toBe(source.list[0]);
+    expect(cloned.list[0].value).toBe('list-value');
+    expect(cloned.self).toBe(cloned);
+    expect(cloned.computed).toBe('computed-value');
+    expect(cloned[symbolKey]).not.toBe(source[symbolKey]);
+    expect(cloned[symbolKey].nested).toBe('symbol-value');
+
+    const [[clonedMapKey, clonedMapValue]] = Array.from(cloned.map.entries());
+    expect(cloned.map).not.toBe(source.map);
+    expect(clonedMapKey).not.toBe(mapKey);
+    expect(clonedMapKey.key).toBe('map-key');
+    expect(clonedMapValue).not.toBe(mapValue);
+    expect(clonedMapValue.value).toBe('map-value');
+
+    const [clonedSetValue] = Array.from(cloned.set.values());
+    expect(cloned.set).not.toBe(source.set);
+    expect(clonedSetValue).not.toBe(setValue);
+    expect(clonedSetValue.value).toBe('set-value');
+  });
+
+  it('deep-freezes objects, maps, sets, and cycles without infinite recursion', () => {
+    const objectValue: { nested: { value: string }; self?: unknown } = {
+      nested: { value: 'nested' },
+    };
+    objectValue.self = objectValue;
+    const mapValue = { value: 'map' };
+    const mapKey = { key: 'map-key' };
+    const setValue = { value: 'set' };
+    const container = {
+      objectValue,
+      map: new Map([[mapKey, mapValue]]),
+      set: new Set([setValue]),
+    };
+
+    const frozen = deepFreeze(container);
+
+    expect(frozen).toBe(container);
+    expect(Object.isFrozen(container)).toBe(true);
+    expect(Object.isFrozen(objectValue)).toBe(true);
+    expect(Object.isFrozen(objectValue.nested)).toBe(true);
+    expect(Object.isFrozen(container.map)).toBe(true);
+    expect(Object.isFrozen(mapKey)).toBe(true);
+    expect(Object.isFrozen(mapValue)).toBe(true);
+    expect(Object.isFrozen(container.set)).toBe(true);
+    expect(Object.isFrozen(setValue)).toBe(true);
+    expect(deepFreeze('already-primitive')).toBe('already-primitive');
+  });
+
+  it('creates immutable clones that cannot be mutated through the original reference', () => {
+    const source = { nested: { value: 'before' }, list: [{ value: 'item' }] };
+    const cloned = immutableClone(source);
+
+    source.nested.value = 'after';
+    source.list[0].value = 'after';
+
+    expect(cloned.nested.value).toBe('before');
+    expect(cloned.list[0].value).toBe('item');
+    expect(Object.isFrozen(cloned)).toBe(true);
+    expect(Object.isFrozen(cloned.nested)).toBe(true);
+    expect(Object.isFrozen(cloned.list)).toBe(true);
+    expect(Object.isFrozen(cloned.list[0])).toBe(true);
+  });
+});
+
+describe('metadata snapshot helpers', () => {
+  const propertyWithoutName = Object.freeze({
+    id: 'snapshot:property:missing:0',
+    kind: 'property',
+    decorator: 'missingName',
+    metadata: undefined,
+    static: false,
+    private: false,
+    order: 0,
+  }) as DecorationRecord;
+
+  const records = Object.freeze([
+    Object.freeze({
+      id: 'snapshot:method:route:2',
+      kind: 'method',
+      decorator: 'route',
+      metadata: { path: '/later' },
+      memberName: 'later',
+      static: false,
+      private: false,
+      order: 2,
+    }) as DecorationRecord,
+    Object.freeze({
+      id: 'snapshot:class:entity:1',
+      kind: 'class',
+      decorator: 'entity',
+      metadata: { table: 'users' },
+      static: false,
+      private: false,
+      order: 1,
+    }) as DecorationRecord,
+    propertyWithoutName,
+    Object.freeze({
+      id: 'snapshot:property:column:3',
+      kind: 'property',
+      decorator: 'column',
+      metadata: { type: 'varchar' },
+      memberName: 'email',
+      static: false,
+      private: false,
+      order: 3,
+    }) as DecorationRecord,
+    Object.freeze({
+      id: 'snapshot:accessor:cached:4',
+      kind: 'accessor',
+      decorator: 'cached',
+      metadata: { ttlMs: 10 },
+      memberName: 'displayName',
+      static: false,
+      private: false,
+      order: 4,
+    }) as DecorationRecord,
+  ]);
+
+  it('sorts records, exposes filtered arrays, and returns frozen copies', () => {
+    const snapshot = createSnapshot(records);
+
+    expect(snapshot.all.map((record) => record.order)).toEqual([0, 1, 2, 3, 4]);
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.all)).toBe(true);
+    expect(Object.isFrozen(snapshot.classes)).toBe(true);
+    expect(Object.isFrozen(snapshot.properties)).toBe(true);
+    expect(Object.isFrozen(snapshot.methods)).toBe(true);
+    expect(Object.isFrozen(snapshot.accessors)).toBe(true);
+
+    expect(snapshot.firstClass('entity')?.metadata).toEqual({ table: 'users' });
+    expect(snapshot.firstClass('controller')).toBeUndefined();
+    expect(snapshot.classRecords()).toHaveLength(1);
+    expect(snapshot.classRecords('entity')).toHaveLength(1);
+    expect(snapshot.classRecords('controller')).toHaveLength(0);
+    expect(snapshot.propertyRecords()).toHaveLength(2);
+    expect(snapshot.propertyRecords('column')).toHaveLength(1);
+    expect(snapshot.methodRecords()).toHaveLength(1);
+    expect(snapshot.methodRecords('route')).toHaveLength(1);
+    expect(snapshot.methodRecords('missing')).toHaveLength(0);
+    expect(snapshot.accessorRecords()).toHaveLength(1);
+    expect(snapshot.accessorRecords('cached')).toHaveLength(1);
+  });
+
+  it('builds readonly member maps with optional decorator filtering', () => {
+    const snapshot = createSnapshot(records);
+
+    const propertyMap = snapshot.propertyMap();
+    const columnMap = snapshot.propertyMap('column');
+    const methodMap = snapshot.methodMap();
+    const routeMap = snapshot.methodMap('route');
+    const missingMethodMap = snapshot.methodMap('missing');
+    const accessorMap = snapshot.accessorMap();
+    const cachedMap = snapshot.accessorMap('cached');
+
+    expect(propertyMap.has('email')).toBe(true);
+    expect(propertyMap.has('missingName')).toBe(false);
+    expect(columnMap.get('email')).toHaveLength(1);
+    expect(methodMap.get('later')).toHaveLength(1);
+    expect(routeMap.get('later')).toHaveLength(1);
+    expect(missingMethodMap.size).toBe(0);
+    expect(accessorMap.get('displayName')).toHaveLength(1);
+    expect(cachedMap.get('displayName')).toHaveLength(1);
+    expect(Object.isFrozen(columnMap.get('email'))).toBe(true);
+  });
+});

package/src/decorators/factory/__tests__/decoratorRegistry.test.ts

@@ -0,0 +1,292 @@
+import { createDecoratorRegistry } from '../index';
+
+type TestSchema = {
+  class: {
+    entity: { metadata: { table: string; nested?: { value: string } } };
+    controller: { metadata: { prefix: string } };
+  };
+  property: {
+    column: {
+      metadata: { type: 'uuid' | 'varchar'; primary?: boolean; nested?: { value: string } };
+      target: string;
+    };
+    serializable: {
+      metadata: undefined;
+      target: unknown;
+    };
+  };
+  method: {
+    route: {
+      metadata: { method: 'GET' | 'POST'; path: string };
+      target: (...args: any[]) => Promise<unknown>;
+    };
+  };
+  accessor: {
+    cached: {
+      metadata: { ttlMs?: number };
+      target: string;
+    };
+  };
+};
+
+type ControllerContract = {
+  id: string;
+  email: string;
+  get(id: string): Promise<{ id: string }>;
+};
+
+function makeDecorators(namespace = 'test') {
+  const registry = createDecoratorRegistry<TestSchema>({ namespace });
+  const Scoped = registry.for<ControllerContract>();
+  return {
+    registry,
+    Entity: Scoped.class('entity'),
+    Controller: Scoped.class('controller'),
+    Column: Scoped.property('column'),
+    Serializable: Scoped.property('serializable'),
+    Route: Scoped.method('route'),
+    Cached: Scoped.accessor('cached'),
+  };
+}
+
+describe('modern decorator registry', () => {
+  it('creates an empty registry snapshot', () => {
+    const { registry } = makeDecorators('empty');
+
+    class Plain {}
+
+    const snapshot = registry.read(Plain);
+    expect(snapshot.all).toHaveLength(0);
+    expect(snapshot.classes).toHaveLength(0);
+    expect(snapshot.properties).toHaveLength(0);
+    expect(snapshot.methods).toHaveLength(0);
+    expect(snapshot.accessors).toHaveLength(0);
+  });
+
+  it('registers class, property, method, and accessor metadata', () => {
+    const { registry, Entity, Column, Serializable, Route, Cached } = makeDecorators('all');
+
+    @Entity({ table: 'users' })
+    class UserController implements ControllerContract {
+      @Column('id', { type: 'uuid', primary: true })
+      id = 'user-1';
+
+      @Serializable.on('email')
+      @Column.on('email', { type: 'varchar' })
+      email = 'ray@example.com';
+
+      @Cached({ ttlMs: 50 })
+      accessor displayName = 'Ray';
+
+      @Route('get', { method: 'GET', path: '/users/:id' })
+      async get(id: string): Promise<{ id: string }> {
+        return { id };
+      }
+    }
+
+    const snapshot = registry.read(UserController);
+
+    expect(snapshot.firstClass('entity')?.metadata).toEqual({ table: 'users' });
+    expect(snapshot.propertyRecords('column')).toHaveLength(2);
+    expect(snapshot.propertyMap('column').get('id')?.[0].metadata).toEqual({
+      type: 'uuid',
+      primary: true,
+    });
+    expect(snapshot.propertyMap('serializable').get('email')).toHaveLength(1);
+    expect(snapshot.methodMap('route').get('get')?.[0].metadata).toEqual({
+      method: 'GET',
+      path: '/users/:id',
+    });
+    expect(snapshot.accessorMap('cached').get('displayName')?.[0].metadata).toEqual({
+      ttlMs: 50,
+    });
+  });
+
+  it('reads metadata from an instance', () => {
+    const { registry, Entity, Column, Route } = makeDecorators('instance');
+
+    @Entity({ table: 'users' })
+    class UserController implements ControllerContract {
+      @Column({ type: 'uuid' })
+      id = 'user-1';
+
+      email = 'ray@example.com';
+
+      @Route({ method: 'GET', path: '/users/:id' })
+      async get(id: string): Promise<{ id: string }> {
+        return { id };
+      }
+    }
+
+    const snapshot = registry.read(new UserController());
+    expect(snapshot.firstClass('entity')?.metadata).toEqual({ table: 'users' });
+    expect(snapshot.propertyMap('column').get('id')).toHaveLength(1);
+  });
+
+  it('deep-clones and freezes metadata at registration time', () => {
+    const { registry, Entity, Column } = makeDecorators('immutability');
+    const classMetadata = { table: 'users', nested: { value: 'before' } };
+    const columnMetadata = { type: 'varchar' as const, nested: { value: 'before' } };
+
+    @Entity(classMetadata)
+    class UserController implements ControllerContract {
+      id = 'user-1';
+
+      @Column(columnMetadata)
+      email = 'ray@example.com';
+
+      async get(id: string): Promise<{ id: string }> {
+        return { id };
+      }
+    }
+
+    classMetadata.nested.value = 'after';
+    columnMetadata.nested.value = 'after';
+
+    const snapshot = registry.read(UserController);
+    const entityMetadata = snapshot.firstClass('entity')?.metadata as typeof classMetadata;
+    const columnRecord = snapshot.propertyMap('column').get('email')?.[0];
+    const storedColumnMetadata = columnRecord?.metadata as typeof columnMetadata;
+
+    expect(entityMetadata.nested.value).toBe('before');
+    expect(storedColumnMetadata.nested.value).toBe('before');
+    expect(Object.isFrozen(entityMetadata)).toBe(true);
+    expect(Object.isFrozen(entityMetadata.nested)).toBe(true);
+    expect(Object.isFrozen(storedColumnMetadata)).toBe(true);
+    expect(Object.isFrozen(storedColumnMetadata.nested)).toBe(true);
+  });
+
+  it('includes inherited metadata by default and can read own metadata only', () => {
+    const { registry, Column, Serializable } = makeDecorators('inheritance');
+
+    class BaseController {
+      @Serializable()
+      id = 'base-id';
+    }
+
+    class UserController extends BaseController implements ControllerContract {
+      @Column({ type: 'varchar' })
+      email = 'ray@example.com';
+
+      async get(id: string): Promise<{ id: string }> {
+        return { id };
+      }
+    }
+
+    const inherited = registry.read(UserController);
+    expect(inherited.propertyRecords('serializable')).toHaveLength(1);
+    expect(inherited.propertyRecords('column')).toHaveLength(1);
+
+    const ownOnly = registry.read(UserController, { includeInherited: false });
+    expect(ownOnly.propertyRecords('serializable')).toHaveLength(0);
+    expect(ownOnly.propertyRecords('column')).toHaveLength(1);
+  });
+
+  it('preserves symbol keys', () => {
+    const { registry, Column } = makeDecorators('symbol');
+    const secret = Symbol('secret');
+
+    class SymbolExample {
+      @Column({ type: 'varchar' })
+      [secret] = 'hidden';
+    }
+
+    const snapshot = registry.read(SymbolExample);
+    expect(snapshot.propertyRecords('column')[0].memberName).toBe(secret);
+    expect(snapshot.propertyMap('column').get(secret)).toHaveLength(1);
+  });
+
+  it('rejects private members by default', () => {
+    const { Column } = makeDecorators('private-reject');
+
+    expect(() => {
+      class PrivateExample {
+        @Column({ type: 'varchar' })
+        #secret = 'hidden';
+
+        reveal() {
+          return this.#secret;
+        }
+      }
+
+      return PrivateExample;
+    }).toThrow(/allowPrivateMembers/);
+  });
+
+  it('allows private members when configured', () => {
+    const registry = createDecoratorRegistry<TestSchema>({
+      namespace: 'private-allow',
+      allowPrivateMembers: true,
+    });
+    const Column = registry.for<{ secret: string }>().property('column');
+
+    class PrivateExample {
+      @Column({ type: 'varchar' })
+      #secret = 'hidden';
+
+      reveal() {
+        return this.#secret;
+      }
+    }
+
+    const snapshot = registry.read(PrivateExample);
+    expect(snapshot.propertyRecords('column')).toHaveLength(1);
+    expect(snapshot.propertyRecords('column')[0].private).toBe(true);
+  });
+
+  it('marks static member records', () => {
+    const { registry, Column, Route } = makeDecorators('static');
+
+    class StaticExample {
+      @Column({ type: 'varchar' })
+      static tableName = 'users';
+
+      @Route({ method: 'GET', path: '/health' })
+      static async health(): Promise<{ id: string }> {
+        return { id: 'ok' };
+      }
+    }
+
+    expect(registry.read(StaticExample).propertyRecords('column')[0].static).toBe(true);
+    expect(registry.read(StaticExample).methodRecords('route')[0].static).toBe(true);
+  });
+
+  it('isolates records by registry namespace and store', () => {
+    type IsolatedSchema = {
+      class: { marker: { metadata: { value: string } } };
+      property: {};
+      method: {};
+      accessor: {};
+    };
+
+    const first = createDecoratorRegistry<IsolatedSchema>({ namespace: 'first' });
+    const second = createDecoratorRegistry<IsolatedSchema>({ namespace: 'second' });
+    const FirstMarker = first.for<object>().class('marker');
+    const SecondMarker = second.for<object>().class('marker');
+
+    @FirstMarker({ value: 'one' })
+    @SecondMarker({ value: 'two' })
+    class Marked {}
+
+    expect(first.read(Marked).classes).toHaveLength(1);
+    expect(second.read(Marked).classes).toHaveLength(1);
+    expect(first.read(Marked).classes[0].id).toContain('first:class:marker');
+    expect(second.read(Marked).classes[0].id).toContain('second:class:marker');
+    expect(first.read(Marked).classes[0].metadata).toEqual({ value: 'one' });
+    expect(second.read(Marked).classes[0].metadata).toEqual({ value: 'two' });
+  });
+
+  it('throws at runtime when a forced keyed decorator is applied to the wrong member', () => {
+    const { Column } = makeDecorators('forced-key');
+    const ForcedColumn = Column as unknown as (...args: unknown[]) => Function;
+
+    expect(() => {
+      class ForcedBadKey {
+        @ForcedColumn('email', { type: 'varchar' })
+        id = 'user-1';
+      }
+
+      return ForcedBadKey;
+    }).toThrow(/keyed for/);
+  });
+});