@cratis/fundamentals 7.17.1 → 7.18.1

package/fieldDecorator.ts

@@ -2,9 +2,10 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { Constructor } from './Constructor';
+import { Field } from './Field';
 import { Fields } from './Fields';
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
+import { addFieldToDecoratorMetadata } from './fieldDecoratorMetadata';
+import { StandardFieldDecoratorContext } from './StandardFieldDecoratorContext';
 
 type fieldOptions = {
     enumerable?: boolean;
@@ -21,7 +22,37 @@ export function field(targetType: Constructor, enumerableOrOptions?: boolean | f
     const actualDerivatives = isFieldOptions(enumerableOrOptions) ? (enumerableOrOptions.derivatives || []) : (derivatives || []);
     const actualGenericArguments = isFieldOptions(enumerableOrOptions) ? (enumerableOrOptions.genericArguments || []) : (genericArguments || []);
 
-    return function (target: any, propertyKey: string) {
-        Fields.addFieldToType(target.constructor, propertyKey, targetType, enumerable, actualDerivatives, actualGenericArguments);
-    };
+    function decorator(target: object, propertyKey: string): void;
+    function decorator(initialValue: undefined, context: StandardFieldDecoratorContext): void;
+    function decorator(targetOrInitialValue: object | undefined, propertyKeyOrContext: string | symbol | StandardFieldDecoratorContext): void {
+        if (typeof propertyKeyOrContext === 'object' && propertyKeyOrContext !== null) {
+            if (targetOrInitialValue !== undefined) throw new TypeError('@field received an invalid standard field value');
+            addStandardField(propertyKeyOrContext);
+            return;
+        }
+
+        addLegacyField(targetOrInitialValue, propertyKeyOrContext);
+    }
+
+    function addStandardField(context: StandardFieldDecoratorContext): void {
+        if (context.kind !== 'field') throw new TypeError('@field can only decorate fields');
+        if (context.static) throw new TypeError('@field cannot decorate static fields');
+        if (context.private) throw new TypeError('@field cannot decorate private fields');
+        if (typeof context.name !== 'string') throw new TypeError('@field cannot decorate symbol-named fields');
+        if (!context.metadata) throw new TypeError('@field requires standard decorator metadata support');
+
+        addFieldToDecoratorMetadata(
+            context.metadata,
+            new Field(context.name, targetType, enumerable, actualDerivatives, actualGenericArguments));
+    }
+
+    function addLegacyField(target: object | undefined, propertyKey: string | symbol): void {
+        if (typeof propertyKey === 'symbol') throw new TypeError('@field cannot decorate symbol-named fields');
+        if (typeof propertyKey !== 'string') throw new TypeError('@field received an invalid legacy decorator invocation');
+        if (!target || typeof target === 'function') throw new TypeError('@field cannot decorate static fields');
+
+        Fields.addFieldToType(target.constructor as Constructor, propertyKey, targetType, enumerable, actualDerivatives, actualGenericArguments);
+    }
+
+    return decorator;
 }

package/fieldDecoratorMetadata.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import './reflection';
+import { Constructor } from './Constructor';
+import { Field } from './Field';
+
+const fieldsMetadataKey = Symbol.for('@cratis/fundamentals.fields');
+
+/**
+ * Adds a field to the metadata object supplied to a standard decorator.
+ * @param metadata The class metadata object supplied by the decorator runtime.
+ * @param field The field to add.
+ */
+export function addFieldToDecoratorMetadata(metadata: Record<PropertyKey, unknown>, field: Field): void {
+    const fields = Reflect.getOwnMetadata(fieldsMetadataKey, metadata) as Map<string, Field> | undefined ?? new Map<string, Field>();
+    fields.set(field.name, field);
+    Reflect.defineMetadata(fieldsMetadataKey, fields, metadata);
+}
+
+/**
+ * Gets the fields stored in the standard decorator metadata owned by a type.
+ * @param target The type to read metadata from.
+ * @returns The fields declared by the type through standard decorators.
+ */
+export function getOwnDecoratorFieldsForType(target: Constructor): Field[] {
+    if (!Object.prototype.hasOwnProperty.call(target, Symbol.metadata)) return [];
+
+    const metadata = (target as Constructor & { [Symbol.metadata]?: Record<PropertyKey, unknown> | null })[Symbol.metadata];
+    if (!metadata) return [];
+
+    const fields = Reflect.getOwnMetadata(fieldsMetadataKey, metadata) as Map<string, Field> | undefined;
+    return fields ? [...fields.values()] : [];
+}

package/for_JsonSerializer/when_metadata_is_written_by_another_copy_of_the_package.ts

@@ -2,17 +2,17 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { DerivedType } from '../DerivedType';
+import { Field } from '../Field';
 import { Fields } from '../Fields';
+import { addFieldToDecoratorMetadata, getOwnDecoratorFieldsForType } from '../fieldDecoratorMetadata';
 
 /**
  * Pins why `Fields` and `DerivedType` were left keyed on the constructor while the converter registry
  * was not.
  *
- * Neither holds state in module scope. Both write reflect metadata keyed on the target constructor, so
- * the state lives with the type being described rather than with the class describing it, and a
- * duplicated `Fields` reads what another `Fields` wrote. (In a real duplicate install the two copies
- * also share one metadata store, because the polyfill installs only when the global `Reflect` lacks it
- * - here a single `reflection` module is loaded, which is the same store by construction.)
+ * Neither holds state in module scope. Legacy metadata is keyed on the target constructor and standard
+ * metadata is keyed on the metadata object attached to that constructor. Both live in the shared
+ * Reflect metadata store, so a duplicated reader can read what another package copy wrote.
  *
  * That is the whole reason those two kept comparing constructors while the converter registry stopped.
  * If it ever stops being true, this goes red and they need the same treatment the converters got.
@@ -22,25 +22,43 @@ describe('when metadata is written by another copy of the package', () => {
     let derivedTypeIsDistinct: boolean;
     let fieldNamesReadByTheOtherCopy: string[];
     let derivedTypeReadByTheOtherCopy: string | undefined;
+    let standardFieldNamesReadByOtherFieldsCopy: string[];
+    let standardFieldNamesReadByTheOtherCopy: string[];
+    let standardMetadataCopiesAreDistinct: boolean;
 
     beforeEach(async () => {
         const otherFields = await import(/* @vite-ignore */ '../Fields?anotherCopy') as typeof import('../Fields');
         const otherDerivedType = await import(/* @vite-ignore */ '../DerivedType?anotherCopy') as typeof import('../DerivedType');
+        const standardMetadataWriter = await import(/* @vite-ignore */ '../fieldDecoratorMetadata?writerCopy') as typeof import('../fieldDecoratorMetadata');
+        const standardMetadataReader = await import(/* @vite-ignore */ '../fieldDecoratorMetadata?readerCopy') as typeof import('../fieldDecoratorMetadata');
 
         fieldsAreDistinct = Fields !== otherFields.Fields;
         derivedTypeIsDistinct = DerivedType !== otherDerivedType.DerivedType;
+        standardMetadataCopiesAreDistinct = standardMetadataWriter.addFieldToDecoratorMetadata !== addFieldToDecoratorMetadata &&
+            standardMetadataReader.getOwnDecoratorFieldsForType !== getOwnDecoratorFieldsForType &&
+            standardMetadataWriter.addFieldToDecoratorMetadata !== standardMetadataReader.addFieldToDecoratorMetadata;
 
         class Subject { }
 
         Fields.addFieldToType(Subject, 'name', String, false, [], []);
         DerivedType.set(Subject, 'an-identifier');
 
+        class StandardSubject { }
+        const metadata: Record<PropertyKey, unknown> = Object.create(null) as Record<PropertyKey, unknown>;
+        standardMetadataWriter.addFieldToDecoratorMetadata(metadata, new Field('standardName', String, false, [], []));
+        Object.defineProperty(StandardSubject, Symbol.metadata, { value: metadata });
+
         fieldNamesReadByTheOtherCopy = otherFields.Fields.getFieldsForType(Subject).map(_ => _.name);
         derivedTypeReadByTheOtherCopy = otherDerivedType.DerivedType.get(Subject);
+        standardFieldNamesReadByTheOtherCopy = standardMetadataReader.getOwnDecoratorFieldsForType(StandardSubject).map(_ => _.name);
+        standardFieldNamesReadByOtherFieldsCopy = otherFields.Fields.getFieldsForType(StandardSubject).map(_ => _.name);
     });
 
     it('should be a genuinely different Fields', () => fieldsAreDistinct.should.be.true);
     it('should be a genuinely different DerivedType', () => derivedTypeIsDistinct.should.be.true);
+    it('should use genuinely different standard metadata helpers', () => standardMetadataCopiesAreDistinct.should.be.true);
     it('should read a field the other copy wrote', () => fieldNamesReadByTheOtherCopy.should.deep.equal(['name']));
     it('should read a derived type the other copy wrote', () => derivedTypeReadByTheOtherCopy!.should.equal('an-identifier'));
+    it('should read a standard field another metadata helper copy wrote', () => standardFieldNamesReadByTheOtherCopy.should.deep.equal(['standardName']));
+    it('should expose standard metadata through another Fields copy', () => standardFieldNamesReadByOtherFieldsCopy.should.deep.equal(['standardName']));
 });

package/for_derivedTypeDecorator/when_an_outer_standard_decorator_replaces_the_class.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '../Constructor';
+import { DerivedType } from '../DerivedType';
+import { derivedType } from '../derivedTypeDecorator';
+
+class BaseType { }
+class OriginalType extends BaseType { }
+class ReplacementType extends OriginalType { }
+
+describe('when an outer standard decorator replaces the class', () => {
+    const initializers: Array<(this: Constructor) => void> = [];
+
+    derivedType('replacement-id')(OriginalType, {
+        addInitializer(initializer) {
+            initializers.push(initializer);
+        },
+        kind: 'class',
+        metadata: {},
+        name: 'OriginalType'
+    });
+    initializers.forEach(initializer => initializer.call(ReplacementType));
+
+    it('should not register the discarded original class', () => (DerivedType.get(OriginalType) === undefined).should.be.true);
+    it('should register the final replacement class', () => DerivedType.get(ReplacementType).should.equal('replacement-id'));
+    it('should register the replacement with its base type', () => DerivedType.getDerivedTypesFor(BaseType).should.deep.equal([ReplacementType]));
+});

package/for_fieldDecorator/fixtures/standard_decorated_types.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+declare const fundamentals: typeof import('../../index');
+
+const { derivedType, field, JsonSerializer, ValueMap } = fundamentals;
+
+function replaceClass<Target extends import('../../Constructor').Constructor>(target: Target): Target {
+    return class extends target { } as Target;
+}
+
+class Shape {
+    @field(String)
+    label!: string;
+}
+
+@derivedType('circle')
+class Circle extends Shape {
+    @field(Number)
+    radius!: number;
+}
+
+@derivedType('rectangle')
+class Rectangle extends Shape {
+    @field(Number)
+    width!: number;
+
+    @field(Number)
+    height!: number;
+}
+
+@replaceClass
+@derivedType('replacement')
+class ReplacedShape extends Shape { }
+
+class Drawing {
+    static instanceCount = 0;
+
+    @field(String)
+    title!: string;
+
+    @field(Date)
+    createdAt!: Date;
+
+    @field(Shape, true)
+    shapes!: Shape[];
+
+    @field(ValueMap, { genericArguments: [String, Number] })
+    scores!: InstanceType<typeof ValueMap<string, number>>;
+
+    constructor() {
+        Drawing.instanceCount++;
+    }
+}
+
+const instanceCountBeforeDeserialize = Drawing.instanceCount;
+const drawing = JsonSerializer.deserialize(Drawing, JSON.stringify({
+    createdAt: '2026-08-16T09:30:00.000Z',
+    scores: {
+        first: 42
+    },
+    shapes: [{
+        _derivedTypeId: 'circle',
+        label: 'First',
+        radius: 12
+    }, {
+        _derivedTypeId: 'rectangle',
+        height: 4,
+        label: 'Second',
+        width: 8
+    }],
+    title: 'Standard decorators'
+}));
+const instanceCountAfterDeserialize = Drawing.instanceCount;
+
+void [Circle, Rectangle, ReplacedShape, instanceCountBeforeDeserialize, drawing, instanceCountAfterDeserialize];

package/for_fieldDecorator/when_executing_standard_typescript_decorator_emit.ts

@@ -0,0 +1,115 @@
+// 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 { fileURLToPath } from 'node:url';
+import { Script } from 'node:vm';
+// TypeScript 7 (the native compiler used for `tsc -b` in this workspace) does not ship the
+// legacy programmatic compiler API (createProgram, transpileModule, etc). This spec needs
+// that API to compile and execute a decorator fixture in-memory, so it imports a nested
+// TypeScript 6 dependency declared under a distinct package name instead of `typescript` -
+// see Source/JavaScript/package.json and the TS6/TS7 side-by-side guidance at
+// https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0
+import { createProgram, getPreEmitDiagnostics, ModuleKind, ModuleResolutionKind, ScriptTarget, transpileModule } from 'typescript-programmatic-api';
+import * as fundamentals from '../index';
+
+describe('when executing standard TypeScript decorator emit', () => {
+    const originalMetadataDescriptor = Object.getOwnPropertyDescriptor(Symbol, 'metadata');
+    let emittedJavaScript: string;
+    let symbolMetadataWasAbsent: boolean;
+    let symbolMetadataWasPolyfilled: boolean;
+    let executionResult: {
+        Circle: fundamentals.Constructor;
+        Drawing: fundamentals.Constructor;
+        Rectangle: fundamentals.Constructor;
+        ReplacedShape: fundamentals.Constructor;
+        Shape: fundamentals.Constructor;
+        drawing: {
+            createdAt: Date;
+            scores: fundamentals.ValueMap<string, number>;
+            shapes: object[];
+            title: string;
+        };
+        instanceCountAfterDeserialize: number;
+        instanceCountBeforeDeserialize: number;
+    };
+    let registeredDerivedTypes: fundamentals.Constructor[];
+    let legacySemanticDiagnosticCount: number;
+    let semanticDiagnosticCount: number;
+
+    beforeAll(async () => {
+        Reflect.deleteProperty(Symbol, 'metadata');
+        symbolMetadataWasAbsent = !Object.prototype.hasOwnProperty.call(Symbol, 'metadata');
+
+        await import(/* @vite-ignore */ '../reflection?standardTypeScriptEmit');
+        symbolMetadataWasPolyfilled = Symbol.metadata === Symbol.for('Symbol.metadata');
+
+        const fixtureUrl = new URL('./fixtures/standard_decorated_types.ts', import.meta.url);
+        const fixturePath = fileURLToPath(fixtureUrl);
+        const source = readFileSync(fixtureUrl, 'utf8');
+        const compilerOptions = {
+            lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
+            module: ModuleKind.ES2022,
+            moduleResolution: ModuleResolutionKind.Bundler,
+            noEmit: true,
+            noImplicitAny: false,
+            skipLibCheck: true,
+            strict: true,
+            target: ScriptTarget.ES2022
+        };
+        const standardProgram = createProgram({
+            options: {
+                ...compilerOptions,
+                emitDecoratorMetadata: false,
+                experimentalDecorators: false,
+            },
+            rootNames: [fixturePath]
+        });
+        const legacyProgram = createProgram({
+            options: {
+                ...compilerOptions,
+                emitDecoratorMetadata: true,
+                experimentalDecorators: true,
+            },
+            rootNames: [fixturePath]
+        });
+        semanticDiagnosticCount = getPreEmitDiagnostics(standardProgram).length;
+        legacySemanticDiagnosticCount = getPreEmitDiagnostics(legacyProgram).length;
+        emittedJavaScript = transpileModule(source, {
+            compilerOptions: {
+                emitDecoratorMetadata: false,
+                experimentalDecorators: false,
+                module: ModuleKind.None,
+                target: ScriptTarget.ES2022
+            },
+            fileName: 'standard_decorated_types.ts',
+            reportDiagnostics: true
+        }).outputText;
+
+        const script = new Script(`${emittedJavaScript}\n({ Circle, Drawing, Rectangle, ReplacedShape, Shape, drawing, instanceCountAfterDeserialize, instanceCountBeforeDeserialize })`);
+        executionResult = script.runInNewContext({ Array, Boolean, Date, fundamentals, JSON, Number, Object, String, Symbol }) as typeof executionResult;
+        registeredDerivedTypes = fundamentals.DerivedType.getDerivedTypesFor(executionResult.Shape);
+    });
+
+    afterAll(() => {
+        Reflect.deleteProperty(Symbol, 'metadata');
+        if (originalMetadataDescriptor) Object.defineProperty(Symbol, 'metadata', originalMetadataDescriptor);
+    });
+
+    it('should begin without runtime Symbol metadata support', () => symbolMetadataWasAbsent.should.be.true);
+    it('should install the Symbol metadata polyfill before class evaluation', () => symbolMetadataWasPolyfilled.should.be.true);
+    it('should type check the standard decorator signatures', () => semanticDiagnosticCount.should.equal(0));
+    it('should type check the legacy decorator signatures', () => legacySemanticDiagnosticCount.should.equal(0));
+    it('should execute standard decorator helper emit', () => emittedJavaScript.should.contain('__esDecorate'));
+    it('should expose field metadata before constructing an instance', () => executionResult.instanceCountBeforeDeserialize.should.equal(0));
+    it('should construct the target only during first-call deserialization', () => executionResult.instanceCountAfterDeserialize.should.equal(1));
+    it('should deserialize primitive fields', () => executionResult.drawing.title.should.equal('Standard decorators'));
+    it('should deserialize date fields', () => executionResult.drawing.createdAt.should.be.instanceOf(Date));
+    it('should deserialize polymorphic array entries', () => (executionResult.drawing.shapes[0] instanceof executionResult.Circle).should.be.true);
+    it('should deserialize every registered derivative', () => (executionResult.drawing.shapes[1] instanceof executionResult.Rectangle).should.be.true);
+    it('should auto-register standard derived type decorators', () => registeredDerivedTypes.should.deep.equal([executionResult.Circle, executionResult.Rectangle, executionResult.ReplacedShape]));
+    it('should register the final class returned by an outer standard decorator', () => fundamentals.DerivedType.get(executionResult.ReplacedShape).should.equal('replacement'));
+    it('should deserialize inherited fields', () => (executionResult.drawing.shapes[0] as { label: string }).label.should.equal('First'));
+    it('should deserialize derived fields', () => (executionResult.drawing.shapes[0] as { radius: number }).radius.should.equal(12));
+    it('should deserialize generic arguments', () => executionResult.drawing.scores.get('first')!.should.equal(42));
+});

package/for_fieldDecorator/when_invoked_as_a_legacy_decorator.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 { Fields } from '../Fields';
+import { field } from '../fieldDecorator';
+
+class FirstDerivative { }
+class SecondDerivative { }
+class LegacyDecoratedType { }
+
+describe('when invoked as a legacy decorator', () => {
+    field(Number)(LegacyDecoratedType.prototype, 'count');
+    field(String, true, [FirstDerivative, SecondDerivative], [String, Number])(LegacyDecoratedType.prototype, 'values');
+
+    const fields = Fields.getFieldsForType(LegacyDecoratedType);
+
+    it('should register a primitive field', () => fields.find(_ => _.name === 'count')!.type.should.equal(Number));
+    it('should preserve enumerable semantics', () => fields.find(_ => _.name === 'values')!.enumerable.should.be.true);
+    it('should preserve derivative semantics', () => fields.find(_ => _.name === 'values')!.derivatives.should.deep.equal([FirstDerivative, SecondDerivative]));
+    it('should preserve generic argument semantics', () => fields.find(_ => _.name === 'values')!.genericArguments.should.deep.equal([String, Number]));
+});

package/for_fieldDecorator/when_invoked_as_a_standard_decorator.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Fields } from '../Fields';
+import { field } from '../fieldDecorator';
+import { StandardFieldDecoratorContext } from '../StandardFieldDecoratorContext';
+
+class FirstDerivative { }
+class SecondDerivative { }
+
+class StandardDecoratedType {
+    static instanceCount = 0;
+
+    constructor() {
+        StandardDecoratedType.instanceCount++;
+    }
+}
+
+describe('when invoked as a standard decorator', () => {
+    const metadata: Record<PropertyKey, unknown> = Object.create(null) as Record<PropertyKey, unknown>;
+    const contextFor = (name: string): StandardFieldDecoratorContext => ({
+        kind: 'field',
+        metadata,
+        name,
+        private: false,
+        static: false
+    });
+
+    field(Number)(undefined, contextFor('count'));
+    field(Date)(undefined, contextFor('createdAt'));
+    field(String, true)(undefined, contextFor('names'));
+    field(Object, { derivatives: [FirstDerivative, SecondDerivative], genericArguments: [String, Number] })(undefined, contextFor('value'));
+    Object.defineProperty(StandardDecoratedType, Symbol.metadata, { value: metadata });
+
+    const fields = Fields.getFieldsForType(StandardDecoratedType);
+
+    it('should expose metadata before constructing an instance', () => StandardDecoratedType.instanceCount.should.equal(0));
+    it('should register a primitive field', () => fields.find(_ => _.name === 'count')!.type.should.equal(Number));
+    it('should register a date field', () => fields.find(_ => _.name === 'createdAt')!.type.should.equal(Date));
+    it('should register an array field', () => fields.find(_ => _.name === 'names')!.enumerable.should.be.true);
+    it('should register derivatives', () => fields.find(_ => _.name === 'value')!.derivatives.should.deep.equal([FirstDerivative, SecondDerivative]));
+    it('should register generic arguments', () => fields.find(_ => _.name === 'value')!.genericArguments.should.deep.equal([String, Number]));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_legacy_field/with_a_static_field.ts

@@ -0,0 +1,12 @@
+// 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 '../../fieldDecorator';
+
+class Subject { }
+
+describe('when invoked for an unsupported legacy field with a static field', () => {
+    const invoke = () => field(String)(Subject, 'value');
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field cannot decorate static fields'));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_legacy_field/with_a_symbol_name.ts

@@ -0,0 +1,12 @@
+// 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 '../../fieldDecorator';
+
+class Subject { }
+
+describe('when invoked for an unsupported legacy field with a symbol name', () => {
+    const invoke = () => field(String)(Subject.prototype, Symbol('value'));
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field cannot decorate symbol-named fields'));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_standard_field/with_a_private_field.ts

@@ -0,0 +1,16 @@
+// 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 '../../fieldDecorator';
+
+describe('when invoked for an unsupported standard field with a private field', () => {
+    const invoke = () => field(String)(undefined, {
+        kind: 'field',
+        metadata: {},
+        name: '#value',
+        private: true,
+        static: false
+    });
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field cannot decorate private fields'));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_standard_field/with_a_static_field.ts

@@ -0,0 +1,16 @@
+// 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 '../../fieldDecorator';
+
+describe('when invoked for an unsupported standard field with a static field', () => {
+    const invoke = () => field(String)(undefined, {
+        kind: 'field',
+        metadata: {},
+        name: 'value',
+        private: false,
+        static: true
+    });
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field cannot decorate static fields'));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_standard_field/with_a_symbol_name.ts

@@ -0,0 +1,16 @@
+// 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 '../../fieldDecorator';
+
+describe('when invoked for an unsupported standard field with a symbol name', () => {
+    const invoke = () => field(String)(undefined, {
+        kind: 'field',
+        metadata: {},
+        name: Symbol('value'),
+        private: false,
+        static: false
+    });
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field cannot decorate symbol-named fields'));
+});

package/for_fieldDecorator/when_invoked_for_an_unsupported_standard_field/without_decorator_metadata.ts

@@ -0,0 +1,16 @@
+// 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 '../../fieldDecorator';
+
+describe('when invoked for an unsupported standard field without decorator metadata', () => {
+    const invoke = () => field(String)(undefined, {
+        kind: 'field',
+        metadata: undefined,
+        name: 'value',
+        private: false,
+        static: false
+    });
+
+    it('should reject the field', () => invoke.should.throw(TypeError, '@field requires standard decorator metadata support'));
+});

package/for_fieldDecorator/when_legacy_and_standard_metadata_are_mixed_across_inheritance.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Fields } from '../Fields';
+import { field } from '../fieldDecorator';
+import { StandardFieldDecoratorContext } from '../StandardFieldDecoratorContext';
+
+class LegacyBase { }
+class StandardDerived extends LegacyBase { }
+class StandardBase { }
+class LegacyDerived extends StandardBase { }
+
+describe('when legacy and standard metadata are mixed across inheritance', () => {
+    const standardDerivedMetadata: Record<PropertyKey, unknown> = Object.create(null) as Record<PropertyKey, unknown>;
+    const standardBaseMetadata: Record<PropertyKey, unknown> = Object.create(null) as Record<PropertyKey, unknown>;
+    const contextFor = (name: string, metadata: Record<PropertyKey, unknown>): StandardFieldDecoratorContext => ({
+        kind: 'field',
+        metadata,
+        name,
+        private: false,
+        static: false
+    });
+
+    field(String)(LegacyBase.prototype, 'value');
+    field(String)(LegacyBase.prototype, 'legacyBaseValue');
+    field(Number)(undefined, contextFor('value', standardDerivedMetadata));
+    field(Number)(undefined, contextFor('standardDerivedValue', standardDerivedMetadata));
+    Object.defineProperty(StandardDerived, Symbol.metadata, { value: standardDerivedMetadata });
+
+    field(String)(undefined, contextFor('value', standardBaseMetadata));
+    field(String)(undefined, contextFor('standardBaseValue', standardBaseMetadata));
+    Object.defineProperty(StandardBase, Symbol.metadata, { value: standardBaseMetadata });
+    field(Boolean)(LegacyDerived.prototype, 'value');
+    field(Boolean)(LegacyDerived.prototype, 'legacyDerivedValue');
+
+    const standardDerivedFields = Fields.getFieldsForType(StandardDerived);
+    const legacyDerivedFields = Fields.getFieldsForType(LegacyDerived);
+
+    it('should inherit legacy fields into a standard derived type', () => standardDerivedFields.find(_ => _.name === 'legacyBaseValue')!.type.should.equal(String));
+    it('should let a standard field override a legacy base field', () => standardDerivedFields.find(_ => _.name === 'value')!.type.should.equal(Number));
+    it('should inherit standard fields into a legacy derived type', () => legacyDerivedFields.find(_ => _.name === 'standardBaseValue')!.type.should.equal(String));
+    it('should let a legacy field override a standard base field', () => legacyDerivedFields.find(_ => _.name === 'value')!.type.should.equal(Boolean));
+});

package/for_fieldDecorator/when_standard_metadata_contains_unrelated_fields_metadata.ts

@@ -0,0 +1,34 @@
+// 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 '../Field';
+import { Fields } from '../Fields';
+import { field } from '../fieldDecorator';
+
+describe('when standard metadata contains unrelated fields metadata', () => {
+    let fields: Field[];
+    let metadata: Record<PropertyKey, unknown>;
+    let unrelatedMetadata: object;
+
+    beforeEach(() => {
+        class Subject { }
+
+        metadata = Object.create(null) as Record<PropertyKey, unknown>;
+        unrelatedMetadata = { source: 'another library' };
+        Reflect.defineMetadata('fields', unrelatedMetadata, metadata);
+
+        field(String)(undefined, {
+            kind: 'field',
+            metadata,
+            name: 'name',
+            private: false,
+            static: false
+        });
+        Object.defineProperty(Subject, Symbol.metadata, { value: metadata });
+        fields = Fields.getFieldsForType(Subject);
+    });
+
+    it('should preserve the unrelated fields metadata', () => Reflect.getOwnMetadata('fields', metadata).should.equal(unrelatedMetadata));
+    it('should register the decorated field independently', () => fields.map(_ => _.name).should.deep.equal(['name']));
+    it('should retain the decorated field type', () => fields[0].type.should.equal(String));
+});