@cratis/chronicle 6.3.2 → 6.4.0

package/projections/modelBound/subtractFrom.ts

@@ -3,6 +3,7 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
+import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the subtractFrom property decorator. */
 export interface SubtractFromMetadata {
@@ -20,14 +21,14 @@ const METADATA_KEY = 'chronicle:projection:subtractFrom';
  * @param eventPropertyName - Optional event property name. Defaults to the property name.
  * @returns A property decorator.
  */
-export function subtractFrom(eventType: Function, eventPropertyName?: string): PropertyDecorator {
-    return (target: object, propertyKey: string | symbol) => {
+export function subtractFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
+    return decorateProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SubtractFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
         const metadata: SubtractFromMetadata = { eventType, eventPropertyName };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
-    };
+    });
 }
 
 /**
@@ -37,5 +38,5 @@ export function subtractFrom(eventType: Function, eventPropertyName?: string): P
  * @returns An array of subtractFrom metadata entries.
  */
 export function getSubtractFromMetadata(target: object, propertyKey: string): SubtractFromMetadata[] {
-    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+    return getPropertyMetadata<SubtractFromMetadata[]>(METADATA_KEY, target, propertyKey) ?? [];
 }

package/readModels/readModel.ts

@@ -6,6 +6,8 @@ import { Constructor } from '@cratis/fundamentals';
 import { ReadModelId } from './ReadModelId.js';
 import { DecoratorType, TypeDiscoverer, TypeIntrospector } from '../types/index.js';
 import { JsonSchema, JsonSchemaGenerator } from '../schemas/index.js';
+import { ChronicleClassDecorator } from '../types/standardDecoratorMetadata.js';
+import { createDeferredSchema } from '../schemas/createDeferredSchema.js';
 
 /** Metadata key used to store read model information on a class. */
 const READ_MODEL_METADATA_KEY = 'chronicle:readModel';
@@ -29,14 +31,23 @@ export interface ReadModelMetadata {
  * @param id - The unique identifier for the read model. Defaults to the class name if omitted.
  * @returns A class decorator.
  */
-export function readModel(id: string = ''): ClassDecorator {
-    return (target: object) => {
-        const constructor = target as Function;
+export function readModel(id: string = ''): ChronicleClassDecorator {
+    return (target: object, context?: ClassDecoratorContext) => {
+        let constructor = target as Function;
         const readModelId = new ReadModelId(id || constructor.name);
-        const members = TypeIntrospector.getMembers(constructor);
-        const metadata: ReadModelMetadata = {
+        const members = context?.kind === 'class' ? undefined : TypeIntrospector.getMembers(constructor);
+        const resolve = createDeferredSchema(() => constructor);
+        const metadata: ReadModelMetadata = context?.kind === 'class' ? {
             id: readModelId,
-            members,
+            get members() {
+                return resolve().members;
+            },
+            get schema() {
+                return resolve().schema;
+            }
+        } : {
+            id: readModelId,
+            members: members!,
             schema: JsonSchemaGenerator.generate(constructor, members)
         };
         Reflect.defineMetadata(READ_MODEL_METADATA_KEY, metadata, target);
@@ -45,6 +56,13 @@ export function readModel(id: string = ''): ClassDecorator {
             constructor as Constructor,
             readModelId.value
         );
+        context?.addInitializer(function () {
+            if (this !== constructor) {
+                constructor = this;
+                Reflect.defineMetadata(READ_MODEL_METADATA_KEY, metadata, constructor);
+                TypeDiscoverer.default.register(DecoratorType.ReadModel, constructor as Constructor, readModelId.value);
+            }
+        });
     };
 }
 

package/readModels/standardFallbacks.standard.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 { field } from '@cratis/fundamentals';
+import { describe, expect, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
+import { ChronicleConnection } from '../connection/ChronicleConnection.js';
+import { reducer } from '../reducers/reducer.js';
+import { MaterializedReadModels } from './MaterializedReadModels.js';
+import { ReadModels } from './ReadModels.js';
+
+class UndecoratedModel {
+    @field(Array) items!: string[];
+}
+
+@reducer('undecorated-model', undefined, UndecoratedModel)
+class ModelReducer {}
+
+const artifacts = {
+    eventTypes: [], readModels: [], reactors: [], reducers: [ModelReducer], seeders: [],
+    constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+} as IClientArtifactsProvider;
+
+describe('standard read models without @readModel', () => {
+    it('rejects an untyped array before registering a reducer read model', async () => {
+        const registerMany = vi.fn();
+        const connection = { readModels: { registerMany } } as unknown as ChronicleConnection;
+        const readModels = new ReadModels('test', 'Default', connection, artifacts, 'sink');
+        await expect(readModels.register(UndecoratedModel)).rejects.toThrow(/Cannot determine the element type of UndecoratedModel.items/);
+        expect(registerMany).not.toHaveBeenCalled();
+    });
+
+    it('rejects an untyped array instead of releasing an incomplete materialized schema', async () => {
+        const getInstances = vi.fn().mockResolvedValue({ Instances: [] });
+        const connection = { materializedReadModels: { getInstances } } as unknown as ChronicleConnection;
+        const materialized = new MaterializedReadModels('test', 'Default', connection);
+        await expect(materialized.getInstances(UndecoratedModel)).rejects.toThrow(/Cannot determine the element type of UndecoratedModel.items/);
+    });
+});

package/schemas/JsonSchemaGenerator.confidentiality.spec.ts

@@ -77,6 +77,8 @@ describe('JsonSchemaGenerator - security metadata', () => {
 
     describe('when a property is typed as a ConceptAs<T> marked @encrypted()', () => {
         class ApiKey extends ConceptAs<string> {
+            static readonly valueType = String;
+
             constructor(value: string) {
                 super(value);
             }

package/schemas/JsonSchemaGenerator.spec.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { ConceptAs, field } from '@cratis/fundamentals';
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
 import { describe, expect, it } from 'vitest';
 import { pii } from '../compliance/pii.js';
 import { eventType, getEventTypeJsonSchemaFor } from '../events/eventTypeDecorator.js';
@@ -22,6 +22,31 @@ function schemaFor(target: Function): JsonSchema {
 }
 
 describe('JsonSchemaGenerator', () => {
+    it('retains the legacy string-concept fallback without emitted type metadata', () => {
+        class LegacyCode extends ConceptAs<string> {}
+        class LegacyModel {
+            code = new LegacyCode('A');
+        }
+        readModel()(LegacyModel);
+        expect(schemaFor(LegacyModel).properties?.code.type).toBe('string');
+    });
+
+    it('preserves Guid and Date-backed legacy concepts with design:type', () => {
+        class LegacyId extends ConceptAs<Guid> {}
+        class LegacyTime extends ConceptAs<Date> {}
+        Reflect.defineMetadata('design:type', Guid, LegacyId.prototype, 'value');
+        Reflect.defineMetadata('design:type', Date, LegacyTime.prototype, 'value');
+        class LegacyEvent {
+            id = new LegacyId(Guid.empty);
+            occurred = new LegacyTime(new Date());
+        }
+        eventType()(LegacyEvent);
+        expect(getEventTypeJsonSchemaFor(LegacyEvent).properties).toMatchObject({
+            id: { type: 'string', format: 'guid' },
+            occurred: { type: 'string', format: 'date-time' }
+        });
+    });
+
     describe('when a class is marked @pii() at the class level', () => {
         class PersonProfile {
             name = '';
@@ -59,6 +84,8 @@ describe('JsonSchemaGenerator', () => {
 
     describe('when a property is typed as a ConceptAs<T> marked @pii()', () => {
         class EmailAddress extends ConceptAs<string> {
+            static readonly valueType = String;
+
             constructor(value: string) {
                 super(value);
             }

package/schemas/JsonSchemaGenerator.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { ConceptAs, Constructor, Fields, Guid } from '@cratis/fundamentals';
+import { conceptAsTypeKey, Constructor, Fields, Guid, typeKeyOf } from '@cratis/fundamentals';
 import { ComplianceSchemaMetadata, JsonSchema, SecuritySchemaMetadata } from './JsonSchema.js';
 import { TypeIntrospector } from '../types/index.js';
+import { hasOwnStandardMetadata } from '../types/standardDecoratorMetadata.js';
 import { ComplianceMetadata } from '../compliance/ComplianceMetadata.js';
 import { ComplianceMetadataResolver } from '../compliance/ComplianceMetadataResolver.js';
 import { SecurityMetadata } from '../confidentiality/SecurityMetadata.js';
@@ -14,6 +15,11 @@ import { PIIAndEncryptedCombinedNotSupported } from '../confidentiality/PIIAndEn
 /**
  * Generates JSON schemas for class constructors using reflection metadata.
  */
+export interface JsonSchemaGenerationOptions {
+    /** Reject members and array elements without runtime types. Defaults to true for standard-decorated classes. */
+    readonly requireResolvedTypes?: boolean;
+}
+
 export class JsonSchemaGenerator {
     private static readonly _knownTypeFormats = new Map<Function, { type: JsonSchema['type']; format: string }>([
         [Guid, { type: 'string', format: 'guid' }],
@@ -44,15 +50,20 @@ export class JsonSchemaGenerator {
      * Generates a JSON schema for a class constructor.
      * @param target - The class constructor to generate schema for.
      * @param members - Optional pre-introspected members for reuse.
+     * @param options - Schema resolution options. A boolean remains supported for existing callers.
      * @returns The generated JSON schema.
      */
-    static generate(target: Function, members?: ReadonlyMap<string, Function | undefined>): JsonSchema {
+    static generate(target: Function, members?: ReadonlyMap<string, Function | undefined>, options?: JsonSchemaGenerationOptions | boolean): JsonSchema {
+        const requireResolvedTypes = typeof options === 'boolean' ? options : options?.requireResolvedTypes ?? hasOwnStandardMetadata(target);
         const membersToUse = members ?? TypeIntrospector.getMembers(target);
         const schemaProperties: Record<string, JsonSchema> = {};
         const prototype = target.prototype;
 
         for (const [memberName, memberType] of membersToUse.entries()) {
-            const propertySchema = this.mapRuntimeTypeToSchema(memberType, target, memberName);
+            if (!memberType && requireResolvedTypes) {
+                throw new TypeError(`Cannot determine the type of ${target.name}.${memberName}; declare @field with its runtime type.`);
+            }
+            const propertySchema = this.mapRuntimeTypeToSchema(memberType, target, memberName, requireResolvedTypes);
             // Only include properties whose type was resolved. An empty schema ({}) means
             // the runtime type was unavailable (e.g. esbuild/tsx omits design:paramtypes).
             if (Object.keys(propertySchema).length > 0) {
@@ -71,9 +82,8 @@ export class JsonSchemaGenerator {
             }
         }
 
-        // When no property types could be resolved, return a minimal schema with empty
-        // properties so the server uses its fallback path that preserves all event
-        // content as-is via ConvertUnknownSchemaTypeToClrType.
+        // Legacy decorators retain the minimal schema fallback for members with no
+        // runtime type metadata. Standard decorators reject unresolved types above.
         if (Object.keys(schemaProperties).length === 0) {
             return this.createEmptySchema(target.name);
         }
@@ -85,7 +95,7 @@ export class JsonSchemaGenerator {
         };
     }
 
-    private static mapRuntimeTypeToSchema(runtimeType: Function | undefined, declaringType?: Function, propertyName?: string): JsonSchema {
+    private static mapRuntimeTypeToSchema(runtimeType: Function | undefined, declaringType?: Function, propertyName?: string, requireResolvedTypes = false): JsonSchema {
         const knownTypeFormat = this.getKnownTypeFormat(runtimeType);
         if (knownTypeFormat) {
             return knownTypeFormat;
@@ -104,25 +114,29 @@ export class JsonSchemaGenerator {
         }
 
         if (runtimeType === Array) {
-            return this.mapArrayTypeToSchema(declaringType, propertyName);
+            return this.mapArrayTypeToSchema(declaringType, propertyName, requireResolvedTypes);
         }
 
         if (!runtimeType) {
             return {};
         }
 
-        // A ConceptAs<T> serializes as its underlying primitive value, so the schema must
-        // describe that primitive rather than the wrapper object. The generic argument T is
-        // not available at runtime, so resolve it from the 'value' property's design:type
-        // when present (ts-node/webpack with emitDecoratorMetadata) and fall back to string
-        // when it is not (esbuild/tsx) — string-backed concepts are by far the common case.
+        // TypeScript erases ConceptAs<T>'s primitive type. Prefer an explicit field or
+        // static hint; legacy emitDecoratorMetadata is the last available source.
         if (this.isConceptAs(runtimeType)) {
-            const valueType = Reflect.getMetadata('design:type', runtimeType.prototype, 'value') as Function | undefined;
-            return this.mapRuntimeTypeToSchema(valueType ?? String);
+            const concept = runtimeType as Function & { valueType?: Function };
+            const fieldType = Fields.getFieldsForType(concept as Constructor).find(field => field.name === 'value')?.type;
+            const valueType = fieldType ?? concept.valueType ?? Reflect.getMetadata('design:type', runtimeType.prototype, 'value') as Function | undefined;
+            if (!valueType && !requireResolvedTypes) return { type: 'string' }; // Legacy schema compatibility.
+            const valueSchema = this.mapRuntimeTypeToSchema(valueType, undefined, undefined, requireResolvedTypes);
+            if (!valueType || !valueSchema.type || (requireResolvedTypes && valueSchema.type === 'object')) {
+                throw new TypeError(`Cannot determine the value type of concept ${runtimeType.name}; declare static readonly valueType = String, Number, Boolean, Guid, or Date.`);
+            }
+            return valueSchema;
         }
 
         if (runtimeType !== Object) {
-            return this.generate(runtimeType);
+            return this.generate(runtimeType, undefined, requireResolvedTypes);
         }
 
         return { type: 'object' };
@@ -135,7 +149,7 @@ export class JsonSchemaGenerator {
      * @param propertyName - The array property name.
      * @returns The array schema, with the element's own compliance metadata carried onto `items` when the element is a PII concept.
      */
-    private static mapArrayTypeToSchema(declaringType: Function | undefined, propertyName: string | undefined): JsonSchema {
+    private static mapArrayTypeToSchema(declaringType: Function | undefined, propertyName: string | undefined, requireResolvedTypes: boolean): JsonSchema {
         const elementType = this.getArrayElementType(declaringType, propertyName);
 
         // An array whose element is a ConceptAs<T> loses its classification the moment it is put in
@@ -143,7 +157,7 @@ export class JsonSchemaGenerator {
         // item schema - a value that would be encrypted as a scalar would otherwise be persisted in
         // the clear as a list element. Mirrors the C# generator's explicit enumerable-of-concept branch.
         if (elementType && this.isConceptAs(elementType)) {
-            const itemSchema = this.mapRuntimeTypeToSchema(elementType);
+            const itemSchema = this.mapRuntimeTypeToSchema(elementType, undefined, undefined, requireResolvedTypes);
             const complianceMetadata = ComplianceMetadataResolver.getMetadataForType(elementType);
             const securityMetadata = SecurityMetadataResolver.getMetadataForType(elementType);
             this.throwIfBothCompliantAndSecure(elementType.name, complianceMetadata, securityMetadata);
@@ -152,7 +166,15 @@ export class JsonSchemaGenerator {
             return { type: 'array', items: itemSchema };
         }
 
-        return { type: 'array', items: { type: 'object' } };
+        if (!elementType) {
+            if (requireResolvedTypes) {
+                throw new TypeError(`Cannot determine the element type of ${declaringType?.name}.${propertyName}; declare @field(Array, { genericArguments: [ItemType] }).`);
+            }
+            return { type: 'array', items: { type: 'object' } };
+        }
+
+        if (!requireResolvedTypes) return { type: 'array', items: { type: 'object' } }; // Legacy schema compatibility.
+        return { type: 'array', items: this.mapRuntimeTypeToSchema(elementType, undefined, undefined, true) };
     }
 
     /**
@@ -189,16 +211,7 @@ export class JsonSchemaGenerator {
     }
 
     private static isConceptAs(runtimeType: Function): boolean {
-        let current: Function | null = runtimeType;
-        while (current && current !== Function.prototype) {
-            if (current === ConceptAs) {
-                return true;
-            }
-
-            current = Object.getPrototypeOf(current) as Function | null;
-        }
-
-        return false;
+        return typeKeyOf(runtimeType as Constructor) === conceptAsTypeKey;
     }
 
     private static getKnownTypeFormat(runtimeType: Function | undefined): JsonSchema | undefined {
@@ -206,7 +219,9 @@ export class JsonSchemaGenerator {
             return undefined;
         }
 
-        const known = this._knownTypeFormats.get(runtimeType);
+        const known = typeKeyOf(runtimeType as Constructor) === 'Guid'
+            ? this._knownTypeFormats.get(Guid)
+            : this._knownTypeFormats.get(runtimeType);
         if (!known) {
             return undefined;
         }

package/schemas/createDeferredSchema.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { JsonSchema } from './JsonSchema.js';
+import { JsonSchemaGenerator } from './JsonSchemaGenerator.js';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
+import { requireCompletedStandardMetadata } from '../types/standardDecoratorMetadata.js';
+
+/** Resolves a standard-decorated class's members and schema together, after class evaluation. */
+export function createDeferredSchema(getType: () => Function): () => { members: ReadonlyMap<string, Function | undefined>; schema: JsonSchema } {
+    let resolved: { members: ReadonlyMap<string, Function | undefined>; schema: JsonSchema } | undefined;
+    return () => {
+        const type = getType();
+        requireCompletedStandardMetadata(type);
+        if (!resolved) {
+            const members = TypeIntrospector.getMembers(type);
+            resolved = { members, schema: JsonSchemaGenerator.generate(type, members, { requireResolvedTypes: true }) };
+        }
+        return resolved;
+    };
+}

package/schemas/decorators.expected.fixture.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { JsonSchema } from './JsonSchema.js';
+
+/** Expected schema contract for both decorator transforms. */
+export const expectedProperties: Record<string, JsonSchema> = {
+    name: { type: 'string' },
+    age: { type: 'number' },
+    active: { type: 'boolean' },
+    id: { type: 'string', format: 'guid' },
+    occurred: { type: 'string', format: 'date-time' },
+    codes: { type: 'array', items: { type: 'string' } },
+    address: {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: 'Address',
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+        additionalProperties: false
+    },
+    code: { type: 'string' },
+    quantity: { type: 'number' }
+};

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');
+    });
+});