@cratis/chronicle 6.3.2 → 6.5.0

package/schemas/decorators.legacy.spec.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { eventType, getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getReadModelMetadata, readModel } from '../readModels/readModel.js';
+import { expectedProperties } from './decorators.expected.fixture.js';
+import { getProjectionMetadata, projection } from '../projections/declarative/projection.js';
+import { getReducerMetadata, reducer } from '../reducers/reducer.js';
+import { getReactorMetadata, reactor } from '../reactors/reactor.js';
+
+class Code extends ConceptAs<string> {
+    static readonly valueType = String;
+}
+
+class Quantity extends ConceptAs<number> {
+    static readonly valueType = Number;
+}
+
+class Address {
+    @field(String) city!: string;
+}
+
+@eventType('legacy-fixture')
+class LegacyEvent {
+    @field(String) name!: string;
+    @field(Number) age!: number;
+    @field(Boolean) active!: boolean;
+    @field(Guid) id!: Guid;
+    @field(Date) occurred!: Date;
+    @field(Array, { genericArguments: [Code] }) codes!: Code[];
+    @field(Address) address!: Address;
+    @field(Code) code!: Code;
+    @field(Quantity) quantity!: Quantity;
+}
+
+@readModel('legacy-model')
+class LegacyModel {
+    @field(Number) count!: number;
+}
+
+@projection('legacy-projection', LegacyModel)
+class LegacyProjection {}
+
+@reducer('legacy-reducer', undefined, LegacyModel)
+class LegacyReducer {}
+
+@reactor('legacy-reactor')
+class LegacyReactor {}
+
+describe('legacy decorator syntax', () => {
+    it('registers the same schemas as standard decorators', () => {
+        expect(getEventTypeMetadata(LegacyEvent)?.eventType.id.value).toBe('legacy-fixture');
+        expect(getReadModelMetadata(LegacyModel)?.schema.properties?.count.type).toBe('number');
+        expect(getEventTypeMetadata(LegacyEvent)?.schema.properties).toEqual(expectedProperties);
+        expect(getEventTypeMetadata(LegacyEvent)?.schema.required).toEqual(Object.keys(expectedProperties));
+        expect(getProjectionMetadata(LegacyProjection)?.id.value).toBe('legacy-projection');
+        expect(getReducerMetadata(LegacyReducer)?.id.value).toBe('legacy-reducer');
+        expect(getReactorMetadata(LegacyReactor)?.id.value).toBe('legacy-reactor');
+    });
+});

package/schemas/decorators.standard.spec.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field, Guid, typeKey } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { eventType, getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getReadModelMetadata, readModel } from '../readModels/readModel.js';
+import { getSetFromMetadata, setFrom } from '../projections/modelBound/setFrom.js';
+import { getProjectionMetadata, projection } from '../projections/declarative/projection.js';
+import { getReducerMetadata, reducer } from '../reducers/reducer.js';
+import { getReactorMetadata, reactor } from '../reactors/reactor.js';
+import { DecoratorType, TypeDiscoverer } from '../types/index.js';
+import { pii } from '../compliance/pii.js';
+import { subject, getSubjectPropertyName } from '../compliance/subject.js';
+import { encrypted } from '../confidentiality/encrypted.js';
+import { JsonSchemaGenerator } from './JsonSchemaGenerator.js';
+import { expectedProperties } from './decorators.expected.fixture.js';
+
+class Code extends ConceptAs<string> {
+    static readonly valueType = String;
+}
+
+class Quantity extends ConceptAs<number> {
+    static readonly valueType = Number;
+}
+
+class Address {
+    @field(String) city!: string;
+}
+
+function replaceClass<T extends new (...args: never[]) => object>(value: T, _context: ClassDecoratorContext<T>): T {
+    return class extends (value as new () => object) {} as T;
+}
+
+@replaceClass
+@eventType('replaced-event')
+class ReplacedEvent {
+    @field(String) value!: string;
+}
+
+@replaceClass
+@readModel('replaced-model')
+class ReplacedModel {
+    @field(Number) amount!: number;
+}
+
+@eventType('standard-fixture')
+class StandardEvent {
+    @field(String) name!: string;
+    @field(Number) age!: number;
+    @field(Boolean) active!: boolean;
+    @field(Guid) id!: Guid;
+    @field(Date) occurred!: Date;
+    @field(Array, { genericArguments: [Code] }) codes!: Code[];
+    @field(Address) address!: Address;
+    @field(Code) code!: Code;
+    @field(Quantity) quantity!: Quantity;
+}
+
+@readModel('standard-model')
+class StandardModel {
+    @field(Number)
+    @setFrom(StandardEvent)
+    count!: number;
+
+    @field(String)
+    @subject()
+    ownerId!: string;
+
+    @field(String)
+    @pii('personal')
+    contact!: string;
+
+    @field(String)
+    @encrypted()
+    secret!: string;
+}
+
+class ParentMapping {
+    @setFrom(StandardEvent) value!: string;
+}
+
+class ChildMapping extends ParentMapping {
+    @setFrom(StandardEvent, 'name') value = '';
+}
+
+@eventType('empty-schema')
+class MissingMembers {}
+
+@readModel('empty-model')
+class EmptyModel {}
+
+@eventType('missing-field')
+class MissingField {
+    constructor(readonly value: string) {}
+}
+
+class UnspecifiedQuantity extends ConceptAs<number> {}
+
+class ConceptGuid extends ConceptAs<Guid> {
+    static readonly valueType = Guid;
+}
+
+class ConceptDate extends ConceptAs<Date> {
+    static readonly valueType = Date;
+}
+
+@eventType('untyped-concept')
+class UntypedConceptEvent {
+    @field(UnspecifiedQuantity) quantity!: UnspecifiedQuantity;
+}
+
+class ForeignConcept {
+    static readonly [typeKey] = 'ConceptAs';
+    static readonly valueType = Number;
+}
+
+class ForeignGuid {
+    static readonly [typeKey] = 'Guid';
+}
+
+@eventType('foreign-types')
+class ForeignTypes {
+    @field(ForeignConcept) amount!: ForeignConcept;
+    @field(ForeignGuid) id!: ForeignGuid;
+    @field(Object) data!: object;
+    @field(ConceptGuid) conceptId!: ConceptGuid;
+    @field(ConceptDate) conceptDate!: ConceptDate;
+    @field(Array, { genericArguments: [String] }) names!: string[];
+    @field(Array, { genericArguments: [Number] }) numbers!: number[];
+    @field(Array, { genericArguments: [Boolean] }) flags!: boolean[];
+    @field(Array, { genericArguments: [Guid] }) guids!: Guid[];
+    @field(Array, { genericArguments: [Address] }) addresses!: Address[];
+}
+
+class UndecoratedModel {
+    @field(Array) items!: string[];
+}
+
+@eventType('untyped-array')
+class UntypedArray {
+    @field(Array) items!: string[];
+}
+
+@projection('standard-projection', StandardModel)
+class StandardProjection {}
+
+@reducer('standard-reducer', undefined, StandardModel)
+class StandardReducer {}
+
+@reactor('standard-reactor')
+class StandardReactor {}
+
+const standardSchema = getEventTypeMetadata(StandardEvent)!.schema;
+
+// No instance is constructed: @field's standard metadata must be available after class evaluation.
+describe('standard decorator syntax', () => {
+    it('registers the event and read model with their declared member types', () => {
+        expect(getEventTypeMetadata(StandardEvent)?.eventType.id.value).toBe('standard-fixture');
+        expect(getReadModelMetadata(StandardModel)?.schema.properties?.count.type).toBe('number');
+        expect(getSetFromMetadata(StandardModel.prototype, 'count')).toEqual([{ eventType: StandardEvent, eventPropertyName: undefined }]);
+        expect(getSubjectPropertyName(StandardModel)).toBe('ownerId');
+        expect(getReadModelMetadata(StandardModel)?.schema.properties?.contact.compliance).toEqual([{ metadataType: 'PII', details: 'personal' }]);
+        expect(getReadModelMetadata(StandardModel)?.schema.properties?.secret.security).toEqual([{ metadataType: 'EncryptedSubject', details: '' }]);
+        expect(standardSchema.properties).toEqual(expectedProperties);
+        expect(standardSchema.required).toEqual(Object.keys(expectedProperties));
+    });
+
+    it('resolves schemas on an outer decorator replacement class', () => {
+        expect(getEventTypeMetadata(ReplacedEvent)!.schema.properties?.value.type).toBe('string');
+        expect(getReadModelMetadata(ReplacedModel)!.schema.properties?.amount.type).toBe('number');
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.EventType, 'replaced-event')).toBe(ReplacedEvent);
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.ReadModel, 'replaced-model')).toBe(ReplacedModel);
+    });
+
+    it('keeps inherited property metadata copy-on-write', () => {
+        expect(getSetFromMetadata(ParentMapping.prototype, 'value')).toHaveLength(1);
+        expect(getSetFromMetadata(ChildMapping.prototype, 'value')).toHaveLength(2);
+        expect(getSetFromMetadata(ParentMapping.prototype, 'value')).toHaveLength(1);
+    });
+
+    it('registers projections, reducers, and reactors', () => {
+        expect(getProjectionMetadata(StandardProjection)?.id.value).toBe('standard-projection');
+        expect(getReducerMetadata(StandardReducer)?.id.value).toBe('standard-reducer');
+        expect(getReactorMetadata(StandardReactor)?.id.value).toBe('standard-reactor');
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.Projection, 'standard-projection')).toBe(StandardProjection);
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.Reducer, 'standard-reducer')).toBe(StandardReducer);
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.Reactor, 'standard-reactor')).toBe(StandardReactor);
+    });
+
+    it('rejects protected event source identifiers in standard mode', () => {
+        expect(() => {
+            class BadPII {
+                @pii() eventSourceId!: string;
+            }
+            void BadPII;
+        }).toThrow(/cannot be applied to 'eventSourceId'/);
+        expect(() => {
+            class BadEncrypted {
+                @encrypted() eventSourceId!: string;
+            }
+            void BadEncrypted;
+        }).toThrow(/cannot be applied to 'eventSourceId'/);
+    });
+
+    it('rejects missing member metadata instead of registering an empty schema', () => {
+        expect(getEventTypeMetadata(MissingMembers)!.schema.properties).toEqual({});
+        expect(getReadModelMetadata(EmptyModel)!.schema.properties).toEqual({});
+        expect(() => getEventTypeMetadata(MissingField)!.schema).toThrow(/Cannot determine the type of MissingField.value/);
+    });
+
+    it('rejects a concept without a declared primitive in standard mode', () => {
+        expect(() => getEventTypeMetadata(UntypedConceptEvent)!.schema).toThrow(/Cannot determine the value type of concept UnspecifiedQuantity/);
+    });
+
+    it('recognizes Fundamentals types from another package copy by their type key', () => {
+        expect(getEventTypeMetadata(ForeignTypes)!.schema.properties).toMatchObject({
+            amount: { type: 'number' },
+            id: { type: 'string', format: 'guid' },
+            data: { type: 'object' },
+            conceptId: { type: 'string', format: 'guid' },
+            conceptDate: { type: 'string', format: 'date-time' },
+            names: { type: 'array', items: { type: 'string' } },
+            numbers: { type: 'array', items: { type: 'number' } },
+            flags: { type: 'array', items: { type: 'boolean' } },
+            guids: { type: 'array', items: { type: 'string', format: 'guid' } },
+            addresses: { type: 'array', items: { type: 'object', properties: { city: { type: 'string' } } } }
+        });
+    });
+
+    it('rejects untyped arrays in standard mode', () => {
+        expect(() => getEventTypeMetadata(UntypedArray)!.schema).toThrow(/Cannot determine the element type of UntypedArray.items/);
+        expect(() => JsonSchemaGenerator.generate(UndecoratedModel)).toThrow(/Cannot determine the element type of UndecoratedModel.items/);
+    });
+});

package/schemas/index.ts

@@ -2,5 +2,6 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export { JsonSchemaGenerator } from './JsonSchemaGenerator.js';
+export type { JsonSchemaGenerationOptions } from './JsonSchemaGenerator.js';
 export { jsonSchemaProperty, getTrackedJsonSchemaProperties } from './jsonSchemaProperty.js';
 export type { ComplianceSchemaMetadata, JsonSchema } from './JsonSchema.js';

package/schemas/jsonSchemaProperty.ts

@@ -3,15 +3,16 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../types/index.js';
+import { ChroniclePropertyDecorator, decorateProperty } from '../types/propertyDecoratorMetadata.js';
 
 /**
  * Decorates a class property so its runtime type metadata can be used for JSON schema generation.
  * @returns A property decorator.
  */
-export function jsonSchemaProperty(): PropertyDecorator {
-    return (target: object, propertyKey: string | symbol) => {
+export function jsonSchemaProperty(): ChroniclePropertyDecorator {
+    return decorateProperty((target: object, propertyKey: string | symbol) => {
         TypeIntrospector.trackProperty(target.constructor as Function, propertyKey.toString());
-    };
+    });
 }
 
 /**

package/schemas/legacyDesignMetadata.spec.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { runInNewContext } from 'node:vm';
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+import { JsonSchemaGenerator } from './JsonSchemaGenerator.js';
+
+const source = `
+function mark() { return () => {}; }
+class LegacyId extends ConceptAs {
+    @mark() value!: Guid;
+}
+class LegacyHolder {
+    @field(LegacyId) id!: LegacyId;
+}
+exports.types = { LegacyId, LegacyHolder };
+`;
+
+const compiled = ts.transpileModule(source, {
+    compilerOptions: {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.CommonJS,
+        experimentalDecorators: true,
+        emitDecoratorMetadata: true
+    }
+}).outputText;
+
+describe('legacy emitDecoratorMetadata compatibility', () => {
+    it('resolves a Guid-backed concept through emitted design:type', () => {
+        const sandbox = { exports: {} as { types?: { LegacyId: Function; LegacyHolder: Function } }, ConceptAs, field, Guid, Reflect };
+        runInNewContext(compiled, sandbox);
+        const { LegacyId, LegacyHolder } = sandbox.exports.types!;
+        expect(Reflect.getMetadata('design:type', LegacyId.prototype, 'value')).toBe(Guid);
+        expect(JsonSchemaGenerator.generate(LegacyHolder).properties?.id).toEqual({ type: 'string', format: 'guid' });
+    });
+});

package/types/TypeIntrospector.ts

@@ -3,6 +3,7 @@
 
 import 'reflect-metadata';
 import { Constructor, Fields } from '@cratis/fundamentals';
+import { getStandardMetadata } from './standardDecoratorMetadata.js';
 
 /** Metadata key for tracked schema properties on a target type. */
 const TRACKED_PROPERTIES_METADATA_KEY = 'chronicle:typeIntrospection:properties';
@@ -31,7 +32,10 @@ export class TypeIntrospector {
      * @returns The tracked property names.
      */
     static getTrackedProperties(target: Function): string[] {
-        return Reflect.getMetadata(TRACKED_PROPERTIES_METADATA_KEY, target) ?? [];
+        const legacy = Reflect.getMetadata(TRACKED_PROPERTIES_METADATA_KEY, target) as string[] | undefined ?? [];
+        const metadata = getStandardMetadata(target);
+        const standard = metadata ? Reflect.getMetadata(TRACKED_PROPERTIES_METADATA_KEY, metadata) as string[] | undefined ?? [] : [];
+        return [...new Set([...legacy, ...standard])];
     }
 
     /**
@@ -63,10 +67,11 @@ export class TypeIntrospector {
         for (const property of propertyNames) {
             let runtimeType = fieldTypes.get(property);
             if (!runtimeType || runtimeType === Object) {
-                runtimeType = Reflect.getMetadata('design:type', target.prototype, property) as Function | undefined;
+                const reflected = Reflect.getMetadata('design:type', target.prototype, property) as Function | undefined;
+                if (reflected && reflected !== Object) runtimeType = reflected;
             }
             if (!runtimeType || runtimeType === Object) {
-                runtimeType = this.getRuntimeTypeFromValue(defaultValues[property]);
+                runtimeType = this.getRuntimeTypeFromValue(defaultValues[property]) ?? runtimeType;
             }
 
             members.set(property, runtimeType);

package/types/index.ts

@@ -4,3 +4,5 @@
 export { DecoratorType } from './DecoratorType.js';
 export { TypeDiscoverer } from './TypeDiscoverer.js';
 export { TypeIntrospector } from './TypeIntrospector.js';
+export type { ChronicleClassDecorator } from './standardDecoratorMetadata.js';
+export type { ChroniclePropertyDecorator, ChronicleClassOrPropertyDecorator } from './propertyDecoratorMetadata.js';

package/types/propertyDecoratorMetadata.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { ChronicleClassDecorator, getStandardMetadata } from './standardDecoratorMetadata.js';
+
+/** A property decorator accepted by both the legacy and standard TypeScript transforms. */
+export type ChroniclePropertyDecorator = PropertyDecorator & ((value: undefined, context: ClassFieldDecoratorContext) => void);
+
+/** A decorator applicable to either a class or a public instance field. */
+export type ChronicleClassOrPropertyDecorator = ChronicleClassDecorator & ChroniclePropertyDecorator;
+
+/** Dispatches class and field decorations while retaining the legacy invocation shape. */
+export function decorateClassOrProperty(legacy: (target: object, property?: string | symbol) => void): ChronicleClassOrPropertyDecorator {
+    const propertyDecorator = decorateProperty(legacy);
+    return (target: object | undefined, propertyOrContext?: string | symbol | ClassDecoratorContext | ClassFieldDecoratorContext) => {
+        if (typeof propertyOrContext === 'object' && propertyOrContext !== null) {
+            if (propertyOrContext.kind === 'class') {
+                if (typeof target !== 'function') throw new TypeError('Chronicle class decorators require a class constructor.');
+                legacy(target);
+            } else {
+                propertyDecorator(target as undefined, propertyOrContext as ClassFieldDecoratorContext);
+            }
+            return;
+        }
+        if (!target) throw new TypeError('Invalid legacy decorator invocation.');
+        legacy(target, propertyOrContext);
+    };
+}
+
+/** Stores standard property annotations on the class metadata object, without constructing an instance. */
+export function decorateProperty(legacy: PropertyDecorator): ChroniclePropertyDecorator {
+    return (target: object | undefined, keyOrContext: string | symbol | ClassFieldDecoratorContext) => {
+        if (typeof keyOrContext === 'object' && keyOrContext !== null) {
+            const context = keyOrContext;
+            if (target !== undefined || context.kind !== 'field' || context.static || context.private || typeof context.name !== 'string' || !context.metadata) {
+                throw new TypeError('Chronicle property decorators require a public instance field with standard decorator metadata.');
+            }
+            // Legacy decorators use target.constructor to track fields and store type-level annotations.
+            // The context.metadata object is owned by this class; never mutate its parent's metadata.
+            Object.defineProperty(context.metadata, 'constructor', { value: context.metadata, configurable: true });
+            legacy(context.metadata, context.name);
+            return;
+        }
+        if (!target || (typeof keyOrContext !== 'string' && typeof keyOrContext !== 'symbol')) {
+            throw new TypeError('Invalid legacy property decorator invocation.');
+        }
+        legacy(target, keyOrContext);
+    };
+}
+
+/** Reads an annotation declared by either decorator transform on a class field. */
+export function getPropertyMetadata<T>(key: string, target: object, property: string): T | undefined {
+    const ownLegacy = Reflect.getOwnMetadata(key, target, property) as T | undefined;
+    if (ownLegacy !== undefined) return ownLegacy;
+    const type = (target as { constructor?: Function }).constructor;
+    const metadata = type && getStandardMetadata(type);
+    const ownStandard = metadata && Reflect.getOwnMetadata(key, metadata, property) as T | undefined;
+    if (ownStandard !== undefined) return ownStandard;
+    return Reflect.getMetadata(key, target, property) as T | undefined
+        ?? (metadata ? Reflect.getMetadata(key, metadata, property) as T | undefined : undefined);
+}
+
+/** Checks whether either decorator transform declared an annotation on a class field. */
+export function hasPropertyMetadata(key: string, target: object, property: string): boolean {
+    const type = (target as { constructor?: Function }).constructor;
+    const metadata = type && getStandardMetadata(type);
+    return Reflect.hasMetadata(key, target, property) || !!metadata && Reflect.hasMetadata(key, metadata, property);
+}
+
+/** Reads a type-level annotation emitted by a standard field decorator (or its legacy equivalent). */
+export function getTypeOrFieldMetadata<T>(key: string, type: Function): T | undefined {
+    const ownLegacy = Reflect.getOwnMetadata(key, type) as T | undefined;
+    if (ownLegacy !== undefined) return ownLegacy;
+    const metadata = getStandardMetadata(type);
+    const ownStandard = metadata && Reflect.getOwnMetadata(key, metadata) as T | undefined;
+    if (ownStandard !== undefined) return ownStandard;
+    return Reflect.getMetadata(key, type) as T | undefined
+        ?? (metadata ? Reflect.getMetadata(key, metadata) as T | undefined : undefined);
+}

package/types/standardDecoratorMetadata.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+const compilerOptions = { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.CommonJS, experimentalDecorators: false };
+const fixture = ts.transpileModule(`
+function mark(_value: Function, context: ClassDecoratorContext) {
+    if (!context.metadata) throw new Error('Missing standard decorator metadata');
+    context.metadata.marked = true;
+}
+@mark class Example {}
+exports.attached = Example[Symbol.metadata]?.marked;
+`, { compilerOptions }).outputText;
+
+const shim = ts.transpileModule(
+    readFileSync(new URL('./standardDecoratorMetadata.ts', import.meta.url), 'utf8'),
+    { compilerOptions }
+).outputText;
+
+describe('standard decorator metadata shim with TypeScript output', () => {
+    it('attaches metadata when the runtime does not provide Symbol.metadata', () => {
+        expect(() => runInNewContext(fixture, { exports: {} })).toThrow('Missing standard decorator metadata');
+        const sandbox = { exports: {} as { attached?: boolean } };
+        runInNewContext(`${shim}\n${fixture}`, sandbox);
+        expect(sandbox.exports.attached).toBe(true);
+    });
+});

package/types/standardDecoratorMetadata.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Node versions without native decorator metadata need this before evaluating a decorated class.
+const symbolWithMetadata = Symbol as unknown as { metadata: symbol };
+symbolWithMetadata.metadata ??= Symbol.for('Symbol.metadata');
+
+/** A class decorator accepted by both the legacy and standard TypeScript transforms. */
+export type ChronicleClassDecorator = ClassDecorator & ((value: Function, context: ClassDecoratorContext) => void);
+
+/** Gets the metadata object attached when a standard-decorated class finishes evaluation. */
+export function getStandardMetadata(type: Function): object | undefined {
+    return Reflect.get(type, symbolWithMetadata.metadata) as object | undefined;
+}
+
+/** Whether a class completed its own standard decorator evaluation. */
+export function hasOwnStandardMetadata(type: Function): boolean {
+    return Object.prototype.hasOwnProperty.call(type, symbolWithMetadata.metadata);
+}
+
+/** Prevents a class decorator from inspecting fields before their metadata is attached. */
+export function requireCompletedStandardMetadata(type: Function): void {
+    if (!hasOwnStandardMetadata(type)) {
+        throw new TypeError(`Standard decorator metadata for ${type.name} is not complete; inspect its schema after class evaluation.`);
+    }
+}

package/vitest.config.ts

@@ -1,9 +1,26 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { transform } from 'esbuild';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+    plugins: [{
+        name: 'standard-decorators-esbuild',
+        enforce: 'pre',
+        async transform(code, id) {
+            const file = id.split('?', 1)[0];
+            if (!file.endsWith('.ts') || file.includes('/node_modules/')) return;
+            return transform(code, {
+                loader: 'ts',
+                sourcefile: file,
+                target: 'es2022',
+                format: 'esm',
+                sourcemap: true,
+                tsconfigRaw: { compilerOptions: { useDefineForClassFields: true, experimentalDecorators: file.endsWith('.legacy.spec.ts') } }
+            });
+        }
+    }],
     test: {
         include: ['**/*.spec.ts', '**/*.spec.js'],
         exclude: ['node_modules', 'dist'],