@travetto/schema 6.0.1 → 7.0.0-rc.0

package/src/service/registry-adapter.ts

@@ -0,0 +1,340 @@
+import type { RegistryAdapter } from '@travetto/registry';
+import { AppError, castKey, castTo, Class, describeFunction, safeAssign } from '@travetto/runtime';
+
+import {
+  SchemaClassConfig, SchemaMethodConfig, SchemaFieldConfig,
+  SchemaParameterConfig, SchemaInputConfig, SchemaFieldMap, SchemaCoreConfig,
+  CONSTRUCTOR_PROPERTY
+} from './types';
+
+const classToDiscriminatedType = (cls: Class): string => cls.name
+  .replace(/([A-Z])([A-Z][a-z])/g, (all, l, r) => `${l}_${r.toLowerCase()}`)
+  .replace(/([a-z]|\b)([A-Z])/g, (all, l, r) => l ? `${l}_${r.toLowerCase()}` : r.toLowerCase())
+  .toLowerCase();
+
+function assignMetadata<T>(key: symbol, base: SchemaCoreConfig, data: Partial<T>[]): T {
+  const md = base.metadata ??= {};
+  const out = md[key] ??= {};
+  for (const d of data) {
+    safeAssign(out, d);
+  }
+  return castTo(out);
+}
+
+function combineCore<T extends SchemaCoreConfig>(base: T, config: Partial<T>): T {
+  return safeAssign(base, {
+    ...config.metadata ? { metadata: { ...base.metadata, ...config.metadata } } : {},
+    ...config.private ? { private: config.private ?? base.private } : {},
+    ...config.description ? { description: config.description || base.description } : {},
+    ...config.examples ? { examples: [...(base.examples ?? []), ...(config.examples ?? [])] } : {},
+  });
+}
+
+function combineInputs<T extends SchemaInputConfig>(base: T, configs: Partial<T>[]): T {
+  for (const config of configs) {
+    safeAssign(base, {
+      ...config,
+      ...config.aliases ? { aliases: [...base.aliases ?? [], ...config.aliases ?? []] } : {},
+      ...config.specifiers ? { specifiers: [...base.specifiers ?? [], ...config.specifiers ?? []] } : {},
+      ...config.enum ? {
+        enum: {
+          message: config.enum?.message ?? base.enum?.message,
+          values: (config.enum?.values ?? base.enum?.values ?? []).toSorted()
+        }
+      } : {},
+    });
+    combineCore(base, config);
+  }
+  return base;
+}
+
+function combineMethods<T extends SchemaMethodConfig>(base: T, configs: Partial<T>[]): T {
+  for (const config of configs) {
+    safeAssign(base, {
+      ...config,
+      parameters: config.parameters ?? base.parameters,
+      validators: [...base.validators, ...(config.validators ?? [])],
+    });
+    combineCore(base, config);
+    if (config.parameters) {
+      for (const param of config.parameters) {
+        safeAssign(base.parameters[param.index], param);
+      }
+    }
+  }
+  return base;
+}
+
+function getConstructorConfig<T extends SchemaClassConfig>(base: Partial<T>, parent?: Partial<T>): SchemaMethodConfig {
+  const parentCons = parent?.methods?.[CONSTRUCTOR_PROPERTY];
+  const baseCons = base.methods?.[CONSTRUCTOR_PROPERTY];
+  return {
+    parameters: [],
+    validators: [],
+    ...parentCons,
+    ...baseCons,
+    returnType: { type: base.class! }
+  };
+}
+
+function combineClassWithParent<T extends SchemaClassConfig>(base: T, parent: T): T {
+  safeAssign(base, {
+    ...base.views ? { views: { ...parent.views, ...base.views } } : {},
+    ...base.validators ? { validators: [...parent.validators, ...base.validators] } : {},
+    ...base.metadata ? { metadata: { ...parent.metadata, ...base.metadata } } : {},
+    interfaces: [...parent.interfaces, ...base.interfaces],
+    methods: { ...parent.methods, ...base.methods },
+    description: base.description || parent.description,
+    examples: [...(parent.examples ?? []), ...(base.examples ?? [])],
+    discriminatedField: base.discriminatedField ?? parent.discriminatedField,
+  });
+  switch (base.mappedOperation) {
+    case 'Required':
+    case 'Partial': {
+      base.fields = Object.fromEntries(
+        Object.entries(base.fields).map(([k, v]) => [k, {
+          ...v,
+          required: {
+            active: base.mappedOperation === 'Required'
+          }
+        }])
+      );
+      break;
+    }
+    case 'Pick':
+    case 'Omit': {
+      const keys = new Set<string>(base.mappedFields ?? []);
+      base.fields = Object.fromEntries(
+        Object.entries(parent.fields).filter(([k]) =>
+          base.mappedOperation === 'Pick' ? keys.has(k) : !keys.has(k)
+        )
+      );
+      break;
+    }
+    default: {
+      base.fields = { ...parent.fields, ...base.fields };
+    }
+  }
+  return base;
+}
+
+function combineClasses<T extends SchemaClassConfig>(base: T, configs: Partial<T>[]): T {
+  for (const config of configs) {
+    Object.assign(base, {
+      ...config,
+      ...config.views ? { views: { ...base.views, ...config.views } } : {},
+      ...config.validators ? { validators: [...base.validators, ...config.validators] } : {},
+      interfaces: [...base.interfaces, ...(config.interfaces ?? [])],
+      methods: { ...base.methods, ...config.methods },
+      fields: { ...base.fields, ...config.fields },
+    });
+    combineCore(base, config);
+  }
+  return base;
+}
+
+export class SchemaRegistryAdapter implements RegistryAdapter<SchemaClassConfig> {
+
+  #cls: Class;
+  #config: SchemaClassConfig;
+  #views: Map<string, SchemaFieldMap> = new Map();
+  #accessorDescriptors: Map<string, PropertyDescriptor> = new Map();
+
+  constructor(cls: Class) {
+    this.#cls = cls;
+  }
+
+  register(...data: Partial<SchemaClassConfig>[]): SchemaClassConfig {
+    const cfg = this.#config ??= {
+      methods: {},
+      class: this.#cls,
+      views: {},
+      validators: [],
+      interfaces: [],
+      fields: {},
+    };
+    return combineClasses(cfg, data);
+  }
+
+  registerMetadata<T>(key: symbol, ...data: Partial<T>[]): T {
+    const cfg = this.register({});
+    return assignMetadata(key, cfg, data);
+  }
+
+  getMetadata<T>(key: symbol): T | undefined {
+    const md = this.#config?.metadata;
+    return castTo<T>(md?.[key]);
+  }
+
+  registerField(field: string | symbol, ...data: Partial<SchemaFieldConfig>[]): SchemaFieldConfig {
+    const config = this.register({});
+    const cfg = config.fields[field] ??= { name: field, owner: this.#cls, type: null! };
+    const combined = combineInputs(cfg, data);
+    return combined;
+  }
+
+  registerFieldMetadata<T>(field: string | symbol, key: symbol, ...data: Partial<T>[]): T {
+    const cfg = this.registerField(field);
+    return assignMetadata(key, cfg, data);
+  }
+
+  getFieldMetadata<T>(field: string | symbol, key: symbol): T | undefined {
+    const md = this.#config?.fields[field]?.metadata;
+    return castTo<T>(md?.[key]);
+  }
+
+  registerClass({ methods, ...cfg }: Partial<SchemaClassConfig> = {}): SchemaClassConfig {
+    this.register({ ...cfg });
+    if (methods?.[CONSTRUCTOR_PROPERTY]) {
+      const { parameters, ...rest } = methods[CONSTRUCTOR_PROPERTY];
+      this.registerMethod(CONSTRUCTOR_PROPERTY, rest);
+      for (const param of parameters ?? []) {
+        this.registerParameter(CONSTRUCTOR_PROPERTY, param.index!, param);
+      }
+    }
+    return this.#config;
+  }
+
+  registerMethod(method: string | symbol, ...data: Partial<SchemaMethodConfig>[]): SchemaMethodConfig {
+    const config = this.register();
+    const cfg = config.methods[method] ??= { parameters: [], validators: [] };
+    return combineMethods(cfg, data);
+  }
+
+  registerMethodMetadata<T>(method: string | symbol, key: symbol, ...data: Partial<T>[]): T {
+    const cfg = this.registerMethod(method);
+    return assignMetadata(key, cfg, data);
+  }
+
+  getMethodMetadata<T>(method: string | symbol, key: symbol): T | undefined {
+    const md = this.#config?.methods[method]?.metadata;
+    return castTo<T>(md?.[key]);
+  }
+
+  registerParameter(method: string | symbol, idx: number, ...data: Partial<SchemaParameterConfig>[]): SchemaParameterConfig {
+    const params = this.registerMethod(method, {}).parameters;
+    const cfg = params[idx] ??= { method, index: idx, owner: this.#cls, array: false, type: null! };
+    return combineInputs(cfg, data);
+  }
+
+  registerParameterMetadata<T>(method: string | symbol, idx: number, key: symbol, ...data: Partial<T>[]): T {
+    const cfg = this.registerParameter(method, idx);
+    return assignMetadata(key, cfg, data);
+  }
+
+  getParameterMetadata<T>(method: string | symbol, idx: number, key: symbol): T | undefined {
+    const md = this.#config?.methods[method]?.parameters[idx]?.metadata;
+    return castTo<T>(md?.[key]);
+  }
+
+  finalize(parent?: SchemaClassConfig): void {
+    const config = this.#config;
+
+    if (parent) {
+      combineClassWithParent(config, parent);
+    }
+
+    if (config.discriminatedField && !config.discriminatedType && !describeFunction(this.#cls).abstract) {
+      config.discriminatedType = classToDiscriminatedType(this.#cls);
+    }
+
+    if (config.discriminatedField && config.discriminatedType) {
+      config.fields[config.discriminatedField] = {
+        ...config.fields[config.discriminatedField], // Make a full copy
+        required: {
+          active: false
+        },
+        enum: {
+          values: [config.discriminatedType],
+          message: `${config.discriminatedField} can only be '${config.discriminatedType}'`,
+        },
+      };
+    }
+
+    // Compute views on install
+    for (const view of Object.keys(config.views)) {
+      const fields = config.views[view];
+      const withoutSet = 'without' in fields ? new Set<string>(fields.without) : undefined;
+      const fieldList = withoutSet ?
+        Object.keys(config.fields).filter(x => !withoutSet.has(x)) :
+        ('with' in fields ? fields.with : []);
+
+      this.#views.set(view,
+        fieldList.reduce<SchemaFieldMap>((acc, v) => {
+          acc[v] = config.fields[v];
+          return acc;
+        }, {})
+      );
+    }
+
+    config.methods[CONSTRUCTOR_PROPERTY] = getConstructorConfig(config, parent);
+
+    for (const method of Object.values(config.methods)) {
+      method.parameters = method.parameters.toSorted((a, b) => (a.index! - b.index!));
+    }
+  }
+
+  get(): SchemaClassConfig {
+    return this.#config;
+  }
+
+  getField(field: string | symbol): SchemaFieldConfig {
+    return this.#config.fields[field];
+  }
+
+  getMethod(method: string | symbol): SchemaMethodConfig {
+    const res = this.#config.methods[method];
+    if (!res) {
+      throw new AppError(`Unknown method ${String(method)} on class ${this.#cls.Ⲑid}`);
+    }
+    return res;
+  }
+
+  getMethodReturnType(method: string | symbol): Class {
+    return this.getMethod(method).returnType!.type;
+  }
+
+  getSchema(view?: string): SchemaFieldMap {
+    if (!view) {
+      return this.#config.fields;
+    }
+    if (!this.#views.has(view)) {
+      throw new AppError(`Unknown view ${view} for class ${this.#cls.Ⲑid}`);
+    }
+    return this.#views.get(view)!;
+  }
+
+  /**
+  * Provides the prototype-derived descriptor for a property
+  */
+  getAccessorDescriptor(field: string): PropertyDescriptor {
+    if (!this.#accessorDescriptors.has(field)) {
+      let proto = this.#cls.prototype;
+      while (proto && !Object.hasOwn(proto, field)) {
+        proto = proto.prototype;
+      }
+      this.#accessorDescriptors.set(field, Object.getOwnPropertyDescriptor(proto, field)!);
+    }
+    return this.#accessorDescriptors.get(field)!;
+  }
+
+  /**
+   * Ensure type is set properly
+   */
+  ensureInstanceTypeField<T>(o: T): T {
+    const config = this.getDiscriminatedConfig();
+    if (config) {
+      const typeField = castKey<T>(config.discriminatedField);
+      o[typeField] ??= castTo(config.discriminatedType); // Assign if missing
+    }
+    return o;
+  }
+
+  getDiscriminatedConfig(): Required<Pick<SchemaClassConfig, 'discriminatedType' | 'discriminatedField' | 'discriminatedBase'>> | undefined {
+    const { discriminatedField, discriminatedType, discriminatedBase } = this.#config;
+    if (discriminatedType && discriminatedField) {
+      return { discriminatedType, discriminatedField, discriminatedBase: !!discriminatedBase };
+    }
+    return undefined;
+  }
+}

package/src/service/registry-index.ts

@@ -0,0 +1,240 @@
+import { ChangeEvent, RegistrationMethods, RegistryIndex, RegistryIndexStore, Registry } from '@travetto/registry';
+import { AppError, castKey, castTo, Class, classConstruct, getParentClass, Util } from '@travetto/runtime';
+
+import { SchemaFieldConfig, SchemaClassConfig, SchemaFieldMap, SchemaMethodConfig } from './types.ts';
+import { SchemaRegistryAdapter } from './registry-adapter.ts';
+import { SchemaChangeListener } from './changes.ts';
+
+/**
+ * Schema registry index for managing schema configurations across classes
+ */
+export class SchemaRegistryIndex implements RegistryIndex {
+
+  static #instance = Registry.registerIndex(SchemaRegistryIndex);
+
+  static getForRegister(cls: Class, allowFinalized = false): SchemaRegistryAdapter {
+    return this.#instance.store.getForRegister(cls, allowFinalized);
+  }
+
+  static getConfig(cls: Class): SchemaClassConfig {
+    return this.#instance.store.get(cls).get();
+  }
+
+  static getDiscriminatedConfig<T>(cls: Class<T>): Required<Pick<SchemaClassConfig, 'discriminatedType' | 'discriminatedField' | 'discriminatedBase'>> | undefined {
+    return this.#instance.store.get(cls).getDiscriminatedConfig();
+  }
+
+  static getFieldMap(cls: Class, view?: string): SchemaFieldMap {
+    return this.#instance.store.get(cls).getSchema(view);
+  }
+
+  static getMethodConfig(cls: Class, method: string | symbol): SchemaMethodConfig {
+    return this.#instance.store.get(cls).getMethod(method);
+  }
+
+  static has(cls: Class): boolean {
+    return this.#instance.store.has(cls);
+  }
+
+  static getClassById(classId: string): Class {
+    return this.#instance.store.getClassById(classId);
+  }
+
+  static getDiscriminatedTypes(cls: Class): string[] | undefined {
+    return this.#instance.getDiscriminatedTypes(cls);
+  }
+
+  static resolveInstanceType<T>(cls: Class<T>, o: T): Class {
+    return this.#instance.resolveInstanceType(cls, o);
+  }
+
+  static visitFields<T>(cls: Class<T>, onField: (field: SchemaFieldConfig, path: SchemaFieldConfig[]) => void): void {
+    return this.#instance.visitFields(cls, onField);
+  }
+
+  static getDiscriminatedClasses(cls: Class): Class[] {
+    return this.#instance.getDiscriminatedClasses(cls);
+  }
+
+  static getBaseClass(cls: Class): Class {
+    return this.#instance.getBaseClass(cls);
+  }
+
+  static get(cls: Class): Omit<SchemaRegistryAdapter, RegistrationMethods> {
+    return this.#instance.store.get(cls);
+  }
+
+  static getOptionalConfig(cls: Class): SchemaClassConfig | undefined {
+    return this.#instance.store.getOptional(cls)?.get();
+  }
+
+  static getClasses(): Class[] {
+    return this.#instance.store.getClasses();
+  }
+
+  store = new RegistryIndexStore(SchemaRegistryAdapter);
+  #baseSchema = new Map<Class, Class>();
+  #byDiscriminatedTypes = new Map<Class, Map<string, Class>>();
+
+  /**
+   * Register discriminated types for a class
+   */
+  #registerDiscriminatedTypes(cls: Class): void {
+    // Mark as subtype
+    const config = this.getClassConfig(cls);
+    if (!config.discriminatedType) {
+      return;
+    }
+    const base = this.getBaseClass(cls);
+    if (!this.#byDiscriminatedTypes.has(base)) {
+      this.#byDiscriminatedTypes.set(base, new Map());
+    }
+    this.#byDiscriminatedTypes.get(base)!.set(config.discriminatedType, cls);
+  }
+
+  #onChanged(event: ChangeEvent<Class> & { type: 'changed' }): void {
+    Util.queueMacroTask().then(() => {
+      SchemaChangeListener.emitFieldChanges({
+        type: 'changed',
+        curr: this.getClassConfig(event.curr),
+        prev: this.getClassConfig(event.prev)
+      });
+    });
+  }
+
+  #onRemoving(event: ChangeEvent<Class> & { type: 'removing' }): void {
+    SchemaChangeListener.clearSchemaDependency(event.prev);
+  }
+
+  #onAdded(event: ChangeEvent<Class> & { type: 'added' }): void {
+    Util.queueMacroTask().then(() => {
+      SchemaChangeListener.emitFieldChanges({
+        type: 'added',
+        curr: this.getClassConfig(event.curr)
+      });
+    });
+  }
+
+  process(events: ChangeEvent<Class>[]): void {
+    for (const event of events) {
+      if (event.type === 'changed') {
+        this.#onChanged(event);
+      } else if (event.type === 'removing') {
+        this.#onRemoving(event);
+      } else if (event.type === 'added') {
+        this.#onAdded(event);
+      }
+    }
+
+    // Rebuild indices after every "process" batch
+    this.#byDiscriminatedTypes.clear();
+    for (const el of this.store.getClasses()) {
+      this.#registerDiscriminatedTypes(el);
+    }
+  }
+
+  getClassConfig(cls: Class): SchemaClassConfig {
+    return this.store.get(cls).get();
+  }
+
+  /**
+   * Find base schema class for a given class
+   */
+  getBaseClass(cls: Class): Class {
+    if (!this.#baseSchema.has(cls)) {
+      let conf = this.getClassConfig(cls);
+      let parent: Class | undefined = cls;
+      while (parent && conf.discriminatedType && !conf.discriminatedBase) {
+        parent = getParentClass(parent);
+        if (parent) {
+          conf = this.store.getOptional(parent)?.get() ?? conf;
+        }
+      }
+      this.#baseSchema.set(cls, conf.class);
+    }
+    return this.#baseSchema.get(cls)!;
+  }
+
+  /**
+   * Find the resolved type for a given instance
+   * @param cls Class for instance
+   * @param o Actual instance
+   */
+  resolveInstanceType<T>(requestedCls: Class<T>, o: T): Class {
+    const cls = this.store.getClassById(requestedCls.Ⲑid); // Resolve by id to handle any stale references
+    const adapter = this.store.get(cls);
+    const { discriminatedField, discriminatedType } = adapter.get();
+    if (!discriminatedField) {
+      return cls;
+    } else {
+      const base = this.getBaseClass(cls);
+      const map = this.#byDiscriminatedTypes.get(base);
+      const type = castTo<string>(o[castKey<T>(discriminatedField)]) ?? discriminatedType;
+      if (!type) {
+        throw new AppError(`Unable to resolve discriminated type for class ${base.name} without a type`);
+      }
+      if (!map?.has(type)) {
+        throw new AppError(`Unable to resolve discriminated type '${type}' for class ${base.name}`);
+      }
+      const requested = map.get(type)!;
+      if (!(classConstruct(requested) instanceof requestedCls)) {
+        throw new AppError(`Resolved discriminated type '${type}' for class ${base.name} is not an instance of requested type ${requestedCls.name}`);
+      }
+      return requested;
+    }
+  }
+
+  /**
+   * Track changes to schemas, and track the dependent changes
+   * @param cls The root class of the hierarchy
+   * @param curr The new class
+   * @param path The path within the object hierarchy
+   */
+  trackSchemaDependencies(cls: Class, curr: Class = cls, path: SchemaFieldConfig[] = []): void {
+    const config = this.getClassConfig(curr);
+
+    SchemaChangeListener.trackSchemaDependency(curr, cls, path, this.getClassConfig(cls));
+
+    // Read children
+    for (const field of Object.values(config.fields)) {
+      if (SchemaRegistryIndex.has(field.type) && field.type !== cls) {
+        this.trackSchemaDependencies(cls, field.type, [...path, field]);
+      }
+    }
+  }
+
+  /**
+   * Visit fields recursively
+   */
+  visitFields<T>(cls: Class<T>, onField: (field: SchemaFieldConfig, path: SchemaFieldConfig[]) => void, _path: SchemaFieldConfig[] = [], root = cls): void {
+    const fields = SchemaRegistryIndex.has(cls) ?
+      Object.values(this.getClassConfig(cls).fields) :
+      [];
+    for (const field of fields) {
+      if (SchemaRegistryIndex.has(field.type)) {
+        this.visitFields(field.type, onField, [..._path, field], root);
+      } else {
+        onField(field, _path);
+      }
+    }
+  }
+
+  /**
+   * Return all subtypes by discriminator for a given class
+   * @param cls The base class to resolve from
+   */
+  getDiscriminatedClasses(cls: Class): Class[] {
+    return [...this.#byDiscriminatedTypes.get(cls)?.values() ?? []];
+  }
+
+  /**
+   * Get all discriminated types for a given class
+   */
+  getDiscriminatedTypes(cls: Class): string[] | undefined {
+    const map = this.#byDiscriminatedTypes.get(cls);
+    if (map) {
+      return [...map.keys()];
+    }
+    return undefined;
+  }
+}