@epsilon-asi/foundation 0.0.1-testing

package/src/decorators/factory/decoratorRegistry.ts

@@ -0,0 +1,366 @@
+import { immutableClone } from './clone';
+import { createSnapshot } from './snapshot';
+import { symbolMetadata } from './symbolMetadata';
+import type {
+  AccessorDecoratorFactory,
+  AnyFunction,
+  Constructor,
+  CreateDecoratorRegistryOptions,
+  DecorationKind,
+  DecorationRecord,
+  DecoratorRegistry,
+  DecoratorSchema,
+  DirectKeyedMetadataArgs,
+  MetadataArgs,
+  MetadataOf,
+  MethodDecoratorFactory,
+  PropertyDecoratorFactory,
+  PublicMemberKey,
+  RegistryMetadataSnapshot,
+  RegistryReadOptions,
+  ScopedDecoratorBuilder,
+  StandardClassDecorator,
+  StringKeyOf,
+  TargetOf,
+  UnscopedClassDecoratorFactory,
+} from './types';
+
+type DecoratorMetadataObject = object;
+
+type ClassOrMemberContext =
+  | ClassDecoratorContext
+  | ClassFieldDecoratorContext
+  | ClassMethodDecoratorContext
+  | ClassAccessorDecoratorContext
+  | ClassGetterDecoratorContext
+  | ClassSetterDecoratorContext;
+
+type MemberContext = Exclude<ClassOrMemberContext, ClassDecoratorContext>;
+
+type ParsedDecoratorArgs = {
+  readonly key?: PublicMemberKey;
+  readonly metadata: unknown;
+};
+
+function isPropertyKey(value: unknown): value is PublicMemberKey {
+  return typeof value === 'string' || typeof value === 'symbol';
+}
+
+function assertPropertyKey(value: unknown, decoratorName: string): PublicMemberKey {
+  if (isPropertyKey(value)) return value;
+  throw new TypeError(
+    `Decorator "${decoratorName}" expected a string or symbol member key, but received ${typeof value}.`,
+  );
+}
+
+function parseDirectArgs(args: readonly unknown[], decoratorName: string): ParsedDecoratorArgs {
+  if (args.length === 0) {
+    return { metadata: undefined };
+  }
+
+  if (args.length === 1) {
+    return { metadata: args[0] };
+  }
+
+  return {
+    key: assertPropertyKey(args[0], decoratorName),
+    metadata: args[1],
+  };
+}
+
+function parseOnArgs(args: readonly unknown[], decoratorName: string): ParsedDecoratorArgs {
+  if (args.length === 0) {
+    throw new TypeError(`Decorator "${decoratorName}.on" requires a member key.`);
+  }
+
+  return {
+    key: assertPropertyKey(args[0], `${decoratorName}.on`),
+    metadata: args.length > 1 ? args[1] : undefined,
+  };
+}
+
+function assertContextKind(
+  expectedKind: DecorationKind,
+  decoratorName: string,
+  context: ClassOrMemberContext,
+): void {
+  if (expectedKind === 'class' && context.kind === 'class') return;
+  if (expectedKind === 'property' && context.kind === 'field') return;
+  if (expectedKind === 'method' && context.kind === 'method') return;
+  if (
+    expectedKind === 'accessor' &&
+    (context.kind === 'accessor' || context.kind === 'getter' || context.kind === 'setter')
+  ) {
+    return;
+  }
+
+  throw new TypeError(
+    `Decorator "${decoratorName}" can only be used on ${expectedKind} targets, but was used on ${context.kind}.`,
+  );
+}
+
+function getTargetConstructor(target: Constructor | object): Constructor | undefined {
+  if (typeof target === 'function') {
+    return target as Constructor;
+  }
+
+  const constructor = target.constructor;
+  return typeof constructor === 'function' ? (constructor as Constructor) : undefined;
+}
+
+function getConstructorChain(constructor: Constructor, includeInherited: boolean): Constructor[] {
+  if (!includeInherited) return [constructor];
+
+  const chain: Constructor[] = [];
+  let current: unknown = constructor;
+
+  while (typeof current === 'function' && current !== Function.prototype) {
+    chain.push(current as Constructor);
+    current = Object.getPrototypeOf(current);
+  }
+
+  return chain.reverse();
+}
+
+function getOwnMetadataObject(constructor: Constructor): DecoratorMetadataObject | undefined {
+  if (!Object.prototype.hasOwnProperty.call(constructor, symbolMetadata)) {
+    return undefined;
+  }
+
+  const metadata = (constructor as unknown as Record<PropertyKey, unknown>)[symbolMetadata];
+  return typeof metadata === 'object' && metadata !== null ? metadata : undefined;
+}
+
+function samePropertyKey(left: PublicMemberKey, right: PublicMemberKey): boolean {
+  return left === right;
+}
+
+class ModernDecoratorRegistry<TSchema extends DecoratorSchema>
+  implements DecoratorRegistry<TSchema>
+{
+  public readonly namespace: string;
+  public readonly allowPrivateMembers: boolean;
+
+  private nextOrder = 0;
+  private readonly recordsByMetadata = new WeakMap<DecoratorMetadataObject, DecorationRecord[]>();
+
+  public constructor(options: CreateDecoratorRegistryOptions = {}) {
+    this.namespace = options.namespace ?? 'default';
+    this.allowPrivateMembers = options.allowPrivateMembers ?? false;
+  }
+
+  public class<K extends StringKeyOf<TSchema['class']>>(
+    name: K,
+  ): UnscopedClassDecoratorFactory<MetadataOf<TSchema['class'][K]>> {
+    return this.createClassFactory(String(name));
+  }
+
+  public for<TContract>(): ScopedDecoratorBuilder<TSchema, TContract> {
+    return Object.freeze({
+      class: <K extends StringKeyOf<TSchema['class']>>(name: K) =>
+        this.createScopedClassFactory<TContract, MetadataOf<TSchema['class'][K]>>(String(name)),
+
+      property: <K extends StringKeyOf<TSchema['property']>>(name: K) =>
+        this.createPropertyFactory<
+          TContract,
+          TargetOf<TSchema['property'][K]>,
+          MetadataOf<TSchema['property'][K]>
+        >(String(name)),
+
+      method: <K extends StringKeyOf<TSchema['method']>>(name: K) =>
+        this.createMethodFactory<
+          TContract,
+          Extract<TargetOf<TSchema['method'][K]>, AnyFunction>,
+          MetadataOf<TSchema['method'][K]>
+        >(String(name)),
+
+      accessor: <K extends StringKeyOf<TSchema['accessor']>>(name: K) =>
+        this.createAccessorFactory<
+          TContract,
+          TargetOf<TSchema['accessor'][K]>,
+          MetadataOf<TSchema['accessor'][K]>
+        >(String(name)),
+    });
+  }
+
+  public read(
+    target: Constructor | object,
+    options: RegistryReadOptions = {},
+  ): RegistryMetadataSnapshot {
+    const constructor = getTargetConstructor(target);
+    if (constructor === undefined) {
+      return createSnapshot([]);
+    }
+
+    const includeInherited = options.includeInherited ?? true;
+    const constructors = getConstructorChain(constructor, includeInherited);
+    const records: DecorationRecord[] = [];
+
+    for (const current of constructors) {
+      const metadata = getOwnMetadataObject(current);
+      if (metadata === undefined) continue;
+
+      const ownRecords = this.recordsByMetadata.get(metadata);
+      if (ownRecords !== undefined) records.push(...ownRecords);
+    }
+
+    return createSnapshot(records);
+  }
+
+  private createClassFactory<TMetadata>(
+    decoratorName: string,
+  ): UnscopedClassDecoratorFactory<TMetadata> {
+    const factory = (<TExpected = unknown>(...args: MetadataArgs<TMetadata>) => {
+      const metadata = args.length === 0 ? undefined : args[0];
+
+      return <TClass extends Constructor<TExpected>>(
+        _value: TClass,
+        context: ClassDecoratorContext<TClass>,
+      ): void => {
+        assertContextKind('class', decoratorName, context);
+        this.register(context.metadata, {
+          kind: 'class',
+          decorator: decoratorName,
+          metadata,
+          static: false,
+          private: false,
+        });
+      };
+    }) as UnscopedClassDecoratorFactory<TMetadata>;
+
+    return factory;
+  }
+
+  private createScopedClassFactory<TContract, TMetadata>(
+    decoratorName: string,
+  ): StandardClassDecorator<TContract, TMetadata> {
+    return ((...args: MetadataArgs<TMetadata>) => {
+      const metadata = args.length === 0 ? undefined : args[0];
+
+      return <TClass extends Constructor<TContract>>(
+        _value: TClass,
+        context: ClassDecoratorContext<TClass>,
+      ): void => {
+        assertContextKind('class', decoratorName, context);
+        this.register(context.metadata, {
+          kind: 'class',
+          decorator: decoratorName,
+          metadata,
+          static: false,
+          private: false,
+        });
+      };
+    }) as StandardClassDecorator<TContract, TMetadata>;
+  }
+
+  private createPropertyFactory<TContract, TTarget, TMetadata>(
+    decoratorName: string,
+  ): PropertyDecoratorFactory<TContract, TTarget, TMetadata> {
+    const factory = ((...args: unknown[]) => {
+      const parsed = parseDirectArgs(args, decoratorName);
+      return this.createMemberDecorator('property', decoratorName, parsed);
+    }) as unknown as PropertyDecoratorFactory<TContract, TTarget, TMetadata>;
+
+    factory.on = ((...args: unknown[]) => {
+      const parsed = parseOnArgs(args, decoratorName);
+      return this.createMemberDecorator('property', decoratorName, parsed);
+    }) as PropertyDecoratorFactory<TContract, TTarget, TMetadata>['on'];
+
+    return factory;
+  }
+
+  private createMethodFactory<TContract, TTarget extends AnyFunction, TMetadata>(
+    decoratorName: string,
+  ): MethodDecoratorFactory<TContract, TTarget, TMetadata> {
+    const factory = ((...args: unknown[]) => {
+      const parsed = parseDirectArgs(args, decoratorName);
+      return this.createMemberDecorator('method', decoratorName, parsed);
+    }) as unknown as MethodDecoratorFactory<TContract, TTarget, TMetadata>;
+
+    factory.on = ((...args: unknown[]) => {
+      const parsed = parseOnArgs(args, decoratorName);
+      return this.createMemberDecorator('method', decoratorName, parsed);
+    }) as MethodDecoratorFactory<TContract, TTarget, TMetadata>['on'];
+
+    return factory;
+  }
+
+  private createAccessorFactory<TContract, TTarget, TMetadata>(
+    decoratorName: string,
+  ): AccessorDecoratorFactory<TContract, TTarget, TMetadata> {
+    const factory = ((...args: unknown[]) => {
+      const parsed = parseDirectArgs(args, decoratorName);
+      return this.createMemberDecorator('accessor', decoratorName, parsed);
+    }) as unknown as AccessorDecoratorFactory<TContract, TTarget, TMetadata>;
+
+    factory.on = ((...args: unknown[]) => {
+      const parsed = parseOnArgs(args, decoratorName);
+      return this.createMemberDecorator('accessor', decoratorName, parsed);
+    }) as AccessorDecoratorFactory<TContract, TTarget, TMetadata>['on'];
+
+    return factory;
+  }
+
+  private createMemberDecorator(
+    kind: Exclude<DecorationKind, 'class'>,
+    decoratorName: string,
+    parsed: ParsedDecoratorArgs,
+  ) {
+    return (_value: unknown, context: MemberContext): void => {
+      assertContextKind(kind, decoratorName, context);
+
+      if (context.private && !this.allowPrivateMembers) {
+        throw new Error(
+          `Decorator "${decoratorName}" cannot be used on private member "${String(
+            context.name,
+          )}" unless allowPrivateMembers is true.`,
+        );
+      }
+
+      if (parsed.key !== undefined && !samePropertyKey(parsed.key, context.name)) {
+        throw new Error(
+          `Decorator "${decoratorName}" was keyed for "${String(
+            parsed.key,
+          )}" but applied to "${String(context.name)}".`,
+        );
+      }
+
+      this.register(context.metadata, {
+        kind,
+        decorator: decoratorName,
+        metadata: parsed.metadata,
+        memberName: context.name,
+        static: context.static,
+        private: context.private,
+      });
+    };
+  }
+
+  private register(
+    metadataObject: DecoratorMetadataObject,
+    record: Omit<DecorationRecord, 'id' | 'order'>,
+  ): void {
+    const order = this.nextOrder;
+    this.nextOrder += 1;
+
+    const immutableRecord = Object.freeze({
+      ...record,
+      id: `${this.namespace}:${record.kind}:${record.decorator}:${order}`,
+      order,
+      metadata: immutableClone(record.metadata),
+    }) as DecorationRecord;
+
+    const existing = this.recordsByMetadata.get(metadataObject);
+    if (existing === undefined) {
+      this.recordsByMetadata.set(metadataObject, [immutableRecord]);
+    } else {
+      existing.push(immutableRecord);
+    }
+  }
+}
+
+export function createDecoratorRegistry<TSchema extends DecoratorSchema>(
+  options: CreateDecoratorRegistryOptions = {},
+): DecoratorRegistry<TSchema> {
+  return new ModernDecoratorRegistry<TSchema>(options);
+}

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

@@ -0,0 +1,38 @@
+import { createDecoratorRegistry } from '../index';
+
+type ViewDecorators = {
+  class: {};
+  property: {};
+  method: {};
+  accessor: {
+    cached: {
+      metadata: { ttlMs?: number };
+      target: string;
+    };
+  };
+};
+
+type UserViewContract = {
+  displayName: string;
+};
+
+const registry = createDecoratorRegistry<ViewDecorators>({ namespace: 'accessor-example' });
+const View = registry.for<UserViewContract>();
+const Cached = View.accessor('cached');
+
+class UserView implements UserViewContract {
+  @Cached('displayName', { ttlMs: 1000 })
+  accessor displayName = 'Ray';
+}
+
+export function readAccessorMetadata(): { memberName: string | symbol; ttlMs: number | undefined }[] {
+  return registry.read(UserView).accessorRecords('cached').map((record) => {
+    if (record.memberName === undefined) throw new Error('Missing member name.');
+    return {
+      memberName: record.memberName,
+      ttlMs: (record.metadata as { ttlMs?: number }).ttlMs,
+    };
+  });
+}
+
+export { UserView, registry as accessorRegistry };

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

@@ -0,0 +1,82 @@
+import { createDecoratorRegistry } from '../index';
+
+type CrudController<TEntity, TCreateInput> = {
+  id: string;
+  get(id: string): Promise<TEntity>;
+  create(input: TCreateInput): Promise<TEntity>;
+};
+
+type UserDto = {
+  id: string;
+  email: string;
+};
+
+type CreateUserInput = {
+  email: string;
+};
+
+type UserCrudController = CrudController<UserDto, CreateUserInput>;
+
+type CrudDecorators = {
+  class: {
+    resource: {
+      metadata: { name: string };
+    };
+  };
+  property: {
+    idField: {
+      metadata: undefined;
+      target: string;
+    };
+  };
+  method: {
+    route: {
+      metadata: { method: 'GET' | 'POST'; path: string };
+      target: (...args: any[]) => Promise<unknown>;
+    };
+  };
+  accessor: {};
+};
+
+const registry = createDecoratorRegistry<CrudDecorators>({ namespace: 'crud-example' });
+const Crud = registry.for<UserCrudController>();
+
+const Resource = Crud.class('resource');
+const IdField = Crud.property('idField');
+const Route = Crud.method('route');
+
+@Resource({ name: 'users' })
+class UserCrud implements UserCrudController {
+  @IdField.on('id')
+  id = 'user-1';
+
+  @Route('get', { method: 'GET', path: '/users/:id' })
+  async get(id: string): Promise<UserDto> {
+    return { id, email: 'ray@example.com' };
+  }
+
+  @Route.on('create', { method: 'POST', path: '/users' })
+  async create(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email };
+  }
+}
+
+export function buildCrudSummary(): { resource: string; routes: string[]; idFields: Array<string | symbol> } {
+  const snapshot = registry.read(UserCrud);
+  const resource = snapshot.firstClass('resource');
+  if (resource === undefined) throw new Error('Missing @Resource metadata.');
+
+  return {
+    resource: (resource.metadata as { name: string }).name,
+    routes: snapshot.methodRecords('route').map((record) => {
+      const metadata = record.metadata as { method: 'GET' | 'POST'; path: string };
+      return `${metadata.method} ${metadata.path}`;
+    }),
+    idFields: snapshot.propertyRecords('idField').map((record) => {
+      if (record.memberName === undefined) throw new Error('Missing member name.');
+      return record.memberName;
+    }),
+  };
+}
+
+export { UserCrud, registry as crudRegistry };

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

@@ -0,0 +1,83 @@
+import { createDecoratorRegistry } from '../index';
+
+type OrmDecorators = {
+  class: {
+    entity: {
+      metadata: { table: string };
+    };
+  };
+  property: {
+    column: {
+      metadata: { type: 'uuid' | 'varchar'; primary?: boolean };
+      target: string;
+    };
+    serializable: {
+      metadata: undefined;
+      target: unknown;
+    };
+  };
+  method: {};
+  accessor: {};
+};
+
+type UserModelContract = {
+  id: string;
+  email: string;
+};
+
+const registry = createDecoratorRegistry<OrmDecorators>({ namespace: 'orm-example' });
+const User = registry.for<UserModelContract>();
+
+const Entity = User.class('entity');
+const Column = User.property('column');
+const Serializable = User.property('serializable');
+
+@Entity({ table: 'users' })
+class UserModel implements UserModelContract {
+  @Column('id', { type: 'uuid', primary: true })
+  @Serializable.on('id')
+  id = 'user-1';
+
+  @Column.on('email', { type: 'varchar' })
+  @Serializable.on('email')
+  email = 'ray@example.com';
+}
+
+export type TableColumn = {
+  name: string | symbol;
+  type: 'uuid' | 'varchar';
+  primary: boolean;
+};
+
+export type TableSchema = {
+  table: string;
+  columns: TableColumn[];
+  serializableFields: Array<string | symbol>;
+};
+
+export function buildUserTableSchema(): TableSchema {
+  const snapshot = registry.read(UserModel);
+  const entity = snapshot.firstClass('entity');
+  if (entity === undefined) throw new Error('Missing @Entity metadata.');
+
+  const tableMetadata = entity.metadata as { table: string };
+  const columns = snapshot.propertyRecords('column').map((record) => {
+    const metadata = record.metadata as { type: 'uuid' | 'varchar'; primary?: boolean };
+    return {
+      name: record.memberName ?? 'unknown',
+      type: metadata.type,
+      primary: metadata.primary ?? false,
+    };
+  });
+
+  return {
+    table: tableMetadata.table,
+    columns,
+    serializableFields: snapshot.propertyRecords('serializable').map((record) => {
+      if (record.memberName === undefined) throw new Error('Serializable record missing member.');
+      return record.memberName;
+    }),
+  };
+}
+
+export { UserModel, registry as ormRegistry };

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

@@ -0,0 +1,70 @@
+import { createDecoratorRegistry } from '../index';
+
+type RouteDecorators = {
+  class: {
+    controller: {
+      metadata: { prefix: string };
+    };
+  };
+  property: {};
+  method: {
+    route: {
+      metadata: { method: 'GET' | 'POST'; path: string };
+      target: (...args: any[]) => Promise<unknown>;
+    };
+  };
+  accessor: {};
+};
+
+type UserDto = { id: string; email: string };
+type CreateUserInput = { email: string };
+
+type UserControllerContract = {
+  getUser(id: string): Promise<UserDto>;
+  createUser(input: CreateUserInput): Promise<UserDto>;
+};
+
+const registry = createDecoratorRegistry<RouteDecorators>({ namespace: 'route-example' });
+const User = registry.for<UserControllerContract>();
+
+const Controller = User.class('controller');
+const Route = User.method('route');
+
+@Controller({ prefix: '/api' })
+class UserController implements UserControllerContract {
+  @Route('getUser', { method: 'GET', path: '/users/:id' })
+  async getUser(id: string): Promise<UserDto> {
+    return { id, email: 'ray@example.com' };
+  }
+
+  @Route.on('createUser', { method: 'POST', path: '/users' })
+  async createUser(input: CreateUserInput): Promise<UserDto> {
+    return { id: 'new-id', email: input.email };
+  }
+}
+
+export type RouteEntry = {
+  httpMethod: 'GET' | 'POST';
+  path: string;
+  handlerName: string | symbol;
+};
+
+export function buildRouteTable(): RouteEntry[] {
+  const snapshot = registry.read(UserController);
+  const controller = snapshot.firstClass('controller');
+  if (controller === undefined) throw new Error('Missing @Controller metadata.');
+
+  const prefix = (controller.metadata as { prefix: string }).prefix;
+
+  return snapshot.methodRecords('route').map((record) => {
+    if (record.memberName === undefined) throw new Error('Route record missing member.');
+    const metadata = record.metadata as { method: 'GET' | 'POST'; path: string };
+    return {
+      httpMethod: metadata.method,
+      path: `${prefix}${metadata.path}`,
+      handlerName: record.memberName,
+    };
+  });
+}
+
+export { UserController, registry as routeRegistry };

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

@@ -0,0 +1,22 @@
+import { readAccessorMetadata } from './accessors';
+import { buildCrudSummary } from './crud';
+import { buildUserTableSchema } from './orm';
+import { buildRouteTable } from './routing';
+import { serializeUser } from './serialization';
+
+function stable(value: unknown): string {
+  return JSON.stringify(value, (_key, innerValue) => {
+    if (typeof innerValue === 'symbol') return innerValue.toString();
+    return innerValue;
+  });
+}
+
+const outputs = {
+  orm: buildUserTableSchema(),
+  routing: buildRouteTable(),
+  serialization: serializeUser(),
+  crud: buildCrudSummary(),
+  accessors: readAccessorMetadata(),
+};
+
+console.log(stable(outputs));