@cratis/chronicle 6.3.1 → 6.4.0

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

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { DecoratorType } from './DecoratorType';
-export { TypeDiscoverer } from './TypeDiscoverer';
-export { TypeIntrospector } from './TypeIntrospector';
+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'],

package/webhooks/IWebhook.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder.js';
 
 /**
  * Defines a discoverable webhook.

package/webhooks/IWebhookDefinitionBuilder.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { Constructor } from '@cratis/fundamentals';
-import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 
 /**
  * Defines a builder for webhook definitions.

package/webhooks/IWebhooks.ts

@@ -2,9 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import type { WebhookDefinition } from '@cratis/chronicle.contracts';
-import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
-import { WebhookId } from './WebhookId';
-import { WebhookTargetUrl } from './WebhookTargetUrl';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder.js';
+import { WebhookId } from './WebhookId.js';
+import { WebhookTargetUrl } from './WebhookTargetUrl.js';
 
 /**
  * Defines the API for working with webhooks.

package/webhooks/WebhookDefinitionBuilder.ts

@@ -9,12 +9,12 @@ import type {
     WebhookDefinition
 } from '@cratis/chronicle.contracts';
 import { Constructor } from '@cratis/fundamentals';
-import { IEventTypes } from '../events/IEventTypes';
-import { getEventTypeFor } from '../events/eventTypeDecorator';
-import { EventSequenceId } from '../eventSequences/EventSequenceId';
-import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
-import { WebhookId } from './WebhookId';
-import { WebhookTargetUrl } from './WebhookTargetUrl';
+import { IEventTypes } from '../events/IEventTypes.js';
+import { getEventTypeFor } from '../events/eventTypeDecorator.js';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder.js';
+import { WebhookId } from './WebhookId.js';
+import { WebhookTargetUrl } from './WebhookTargetUrl.js';
 
 /**
  * Implements {@link IWebhookDefinitionBuilder}.

package/webhooks/Webhooks.ts

@@ -3,18 +3,18 @@
 
 import { type WebhookDefinition } from '@cratis/chronicle.contracts';
 import { Constructor } from '@cratis/fundamentals';
-import { IClientArtifactsProvider } from '../artifacts';
-import { ChronicleConnection } from '../connection';
-import { ensureCommandSuccess, ensureQuerySuccess } from '../connection/callResults';
-import { EventSequenceId } from '../eventSequences/EventSequenceId';
-import { IEventTypes } from '../events/IEventTypes';
-import { IWebhook } from './IWebhook';
-import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
-import { IWebhooks } from './IWebhooks';
-import { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
-import { WebhookId } from './WebhookId';
-import { WebhookTargetUrl } from './WebhookTargetUrl';
-import { getWebhookMetadata } from './webhook';
+import { IClientArtifactsProvider } from '../artifacts/index.js';
+import { ChronicleConnection } from '../connection/index.js';
+import { ensureCommandSuccess, ensureQuerySuccess } from '../connection/callResults.js';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { IEventTypes } from '../events/IEventTypes.js';
+import { IWebhook } from './IWebhook.js';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder.js';
+import { IWebhooks } from './IWebhooks.js';
+import { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder.js';
+import { WebhookId } from './WebhookId.js';
+import { WebhookTargetUrl } from './WebhookTargetUrl.js';
+import { getWebhookMetadata } from './webhook.js';
 
 /**
  * Implements {@link IWebhooks}.

package/webhooks/index.ts

@@ -1,12 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { WebhookId } from './WebhookId';
-export { WebhookTargetUrl } from './WebhookTargetUrl';
-export { webhook, getWebhookMetadata, isWebhook } from './webhook';
-export type { WebhookMetadata } from './webhook';
-export type { IWebhook } from './IWebhook';
-export type { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
-export type { IWebhooks } from './IWebhooks';
-export { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
-export { Webhooks } from './Webhooks';
+export { WebhookId } from './WebhookId.js';
+export { WebhookTargetUrl } from './WebhookTargetUrl.js';
+export { webhook, getWebhookMetadata, isWebhook } from './webhook.js';
+export type { WebhookMetadata } from './webhook.js';
+export type { IWebhook } from './IWebhook.js';
+export type { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder.js';
+export type { IWebhooks } from './IWebhooks.js';
+export { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder.js';
+export { Webhooks } from './Webhooks.js';

package/webhooks/webhook.ts

@@ -3,9 +3,9 @@
 
 import 'reflect-metadata';
 import { Constructor } from '@cratis/fundamentals';
-import { DecoratorType, TypeDiscoverer } from '../types';
-import { WebhookId } from './WebhookId';
-import { WebhookTargetUrl } from './WebhookTargetUrl';
+import { DecoratorType, TypeDiscoverer } from '../types/index.js';
+import { WebhookId } from './WebhookId.js';
+import { WebhookTargetUrl } from './WebhookTargetUrl.js';
 
 /** Metadata key used to store webhook information on a class. */
 const WEBHOOK_METADATA_KEY = 'chronicle:webhook';