@epsilon-asi/foundation 0.0.1-testing

package/src/decorators/factory/examples/serialization.ts

@@ -0,0 +1,47 @@
+import { createDecoratorRegistry } from '../index';
+
+type SerializationDecorators = {
+  class: {};
+  property: {
+    serializable: {
+      metadata: undefined;
+      target: unknown;
+    };
+  };
+  method: {};
+  accessor: {};
+};
+
+type UserContract = {
+  id: string;
+  email: string;
+  passwordHash: string;
+};
+
+const registry = createDecoratorRegistry<SerializationDecorators>({ namespace: 'serialization-example' });
+const User = registry.for<UserContract>();
+const Serializable = User.property('serializable');
+
+class UserRecord implements UserContract {
+  @Serializable.on('id')
+  id = 'user-1';
+
+  @Serializable.on('email')
+  email = 'ray@example.com';
+
+  passwordHash = 'not-for-output';
+}
+
+export function serializeUser(user = new UserRecord()): Record<string, unknown> {
+  const snapshot = registry.read(user);
+  const output: Record<string, unknown> = {};
+
+  for (const record of snapshot.propertyRecords('serializable')) {
+    if (typeof record.memberName !== 'string') continue;
+    output[record.memberName] = (user as unknown as Record<string, unknown>)[record.memberName];
+  }
+
+  return output;
+}
+
+export { UserRecord, registry as serializationRegistry };

package/src/decorators/factory/index.ts

@@ -0,0 +1,20 @@
+export { createDecoratorRegistry } from './decoratorRegistry';
+export { ensureSymbolMetadata, symbolMetadata } from './symbolMetadata';
+export type {
+  AccessorDecoratorDefinition,
+  AnyFunction,
+  ClassDecoratorDefinition,
+  Constructor,
+  CreateDecoratorRegistryOptions,
+  DecorationKind,
+  DecorationRecord,
+  DecoratorRegistry,
+  DecoratorSchema,
+  MethodDecoratorDefinition,
+  MetadataOf,
+  PropertyDecoratorDefinition,
+  RegistryMetadataSnapshot,
+  RegistryReadOptions,
+  ScopedDecoratorBuilder,
+  TargetOf,
+} from './types';

package/src/decorators/factory/snapshot.ts

@@ -0,0 +1,95 @@
+import type { DecorationKind, DecorationRecord, RegistryMetadataSnapshot } from './types';
+
+function cloneRecords(records: readonly DecorationRecord[]): readonly DecorationRecord[] {
+  return Object.freeze(records.slice());
+}
+
+function filterRecords(
+  records: readonly DecorationRecord[],
+  kind: DecorationKind,
+  decorator?: string,
+): readonly DecorationRecord[] {
+  return Object.freeze(
+    records.filter((record) => {
+      if (record.kind !== kind) return false;
+      return decorator === undefined || record.decorator === decorator;
+    }),
+  );
+}
+
+function memberMap(
+  records: readonly DecorationRecord[],
+  kind: 'property' | 'method' | 'accessor',
+  decorator?: string,
+): ReadonlyMap<string | symbol, readonly DecorationRecord[]> {
+  const mutable = new Map<string | symbol, DecorationRecord[]>();
+
+  for (const record of records) {
+    if (record.kind !== kind) continue;
+    if (decorator !== undefined && record.decorator !== decorator) continue;
+    if (record.memberName === undefined) continue;
+
+    const existing = mutable.get(record.memberName);
+    if (existing === undefined) {
+      mutable.set(record.memberName, [record]);
+    } else {
+      existing.push(record);
+    }
+  }
+
+  const frozen = new Map<string | symbol, readonly DecorationRecord[]>();
+  for (const [key, value] of mutable.entries()) {
+    frozen.set(key, Object.freeze(value.slice()));
+  }
+
+  return frozen;
+}
+
+export function createSnapshot(records: readonly DecorationRecord[]): RegistryMetadataSnapshot {
+  const sorted = records.slice().sort((left, right) => left.order - right.order);
+  const all = cloneRecords(sorted);
+  const classes = filterRecords(all, 'class');
+  const properties = filterRecords(all, 'property');
+  const methods = filterRecords(all, 'method');
+  const accessors = filterRecords(all, 'accessor');
+
+  return Object.freeze({
+    all,
+    classes,
+    properties,
+    methods,
+    accessors,
+
+    firstClass(decorator: string) {
+      return classes.find((record) => record.decorator === decorator);
+    },
+
+    classRecords(decorator?: string) {
+      return filterRecords(all, 'class', decorator);
+    },
+
+    propertyRecords(decorator?: string) {
+      return filterRecords(all, 'property', decorator);
+    },
+
+    methodRecords(decorator?: string) {
+      return filterRecords(all, 'method', decorator);
+    },
+
+    accessorRecords(decorator?: string) {
+      return filterRecords(all, 'accessor', decorator);
+    },
+
+    propertyMap(decorator?: string) {
+      return memberMap(all, 'property', decorator);
+    },
+
+    methodMap(decorator?: string) {
+      return memberMap(all, 'method', decorator);
+    },
+
+    accessorMap(decorator?: string) {
+      return memberMap(all, 'accessor', decorator);
+    },
+  });
+}

package/src/decorators/factory/symbolMetadata.ts

@@ -0,0 +1,20 @@
+type SymbolConstructorWithMetadata = SymbolConstructor & {
+  metadata?: symbol;
+};
+
+export function ensureSymbolMetadata(): symbol {
+  const symbolConstructor = Symbol as SymbolConstructorWithMetadata;
+
+  if (symbolConstructor.metadata === undefined) {
+    Object.defineProperty(symbolConstructor, 'metadata', {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: Symbol('Symbol.metadata'),
+    });
+  }
+
+  return symbolConstructor.metadata;
+}
+
+export const symbolMetadata = ensureSymbolMetadata();

package/src/decorators/factory/type-tests/decoratorRegistry.type-test.ts

@@ -0,0 +1,302 @@
+import { createDecoratorRegistry } from '../index';
+
+type UserDto = {
+  id: string;
+  email: string;
+  age: number;
+};
+
+type CreateUserInput = {
+  email: string;
+  age: number;
+};
+
+interface UserControllerContract {
+  id: string;
+  email: string;
+  age: number;
+  getUser(id: string): Promise<UserDto>;
+  createUser(input: CreateUserInput): Promise<UserDto>;
+}
+
+type AppDecorators = {
+  class: {
+    entity: {
+      metadata: { table: string };
+    };
+  };
+  property: {
+    column: {
+      metadata: { type: 'uuid' | 'varchar'; primary?: boolean };
+      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;
+    };
+  };
+};
+
+const registry = createDecoratorRegistry<AppDecorators>();
+const Entity = registry.class('entity');
+const User = registry.for<UserControllerContract>();
+const ScopedEntity = User.class('entity');
+const Column = User.property('column');
+const Serializable = User.property('serializable');
+const Route = User.method('route');
+const Cached = User.accessor('cached');
+
+@Entity<UserControllerContract>({ table: 'users' })
+class GoodUnscopedUserController implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+// @ts-expect-error missing contract members
+@Entity<UserControllerContract>({ table: 'users' })
+class BadUnscopedUserController {}
+
+// @ts-expect-error table must be string
+@Entity<UserControllerContract>({ table: 123 })
+class BadClassMetadataController implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+@ScopedEntity({ table: 'users' })
+class GoodScopedUserController implements UserControllerContract {
+  @Column({ type: 'uuid', primary: true })
+  id!: string;
+
+  @Serializable()
+  @Column('email', { type: 'varchar' })
+  email!: string;
+
+  age!: number;
+
+  @Route({ method: 'GET', path: '/users/:id' })
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  @Route.on('createUser', { method: 'POST', path: '/users' })
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadPropertyMetadata implements UserControllerContract {
+  // @ts-expect-error type must be uuid or varchar
+  @Column({ type: 'int' })
+  id!: string;
+
+  email!: string;
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadPropertyTarget implements UserControllerContract {
+  id!: string;
+  email!: string;
+
+  // @ts-expect-error column target is string but age is number
+  @Column({ type: 'varchar' })
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadPropertyKey implements UserControllerContract {
+  // @ts-expect-error decorator key does not match member name
+  @Column('email', { type: 'varchar' })
+  id!: string;
+
+  email!: string;
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadNoMetadataArgs implements UserControllerContract {
+  id!: string;
+
+  // @ts-expect-error Serializable takes no metadata
+  @Serializable({ enabled: true })
+  email!: string;
+
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadRequiredMetadataArgs implements UserControllerContract {
+  // @ts-expect-error Column requires metadata
+  @Column()
+  id!: string;
+
+  email!: string;
+  age!: number;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadMethodMetadata implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  // @ts-expect-error DELETE is not allowed
+  @Route({ method: 'DELETE', path: '/users/:id' })
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadMethodTarget {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  // @ts-expect-error route target requires Promise return
+  @Route({ method: 'GET', path: '/users/:id' })
+  getUser(id: string): UserDto {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadMethodKey implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  // @ts-expect-error decorator key does not match method name
+  @Route('createUser', { method: 'GET', path: '/users/:id' })
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class GoodAccessor implements UserControllerContract {
+  id!: string;
+  age!: number;
+
+  @Cached('email', { ttlMs: 1000 })
+  accessor email = 'Ray';
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadAccessorTarget implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  // @ts-expect-error cached target is string but count is number
+  @Cached({ ttlMs: 1000 })
+  accessor count = 1;
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}
+
+class BadAccessorMetadata implements UserControllerContract {
+  id!: string;
+  email!: string;
+  age!: number;
+
+  // @ts-expect-error ttlMs must be number
+  @Cached({ ttlMs: '1000' })
+  accessor label = 'Ray';
+
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: this.email, age: this.age };
+  }
+
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email, age: input.age };
+  }
+}