@cratis/fundamentals 7.16.7 → 7.17.0

package/for_duplicateInstanceGuard/given/a_realm.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.
+
+const loadedInstancesKey = Symbol.for('@cratis/fundamentals.loadedInstances');
+const duplicateReportedKey = Symbol.for('@cratis/fundamentals.duplicateReported');
+
+const globals = globalThis as Record<symbol, unknown>;
+
+/** The part of the guard's surface a spec drives. */
+type PackageCopy = {
+    registerModuleInstance(): void;
+};
+
+let copiesLoaded = 0;
+
+/**
+ * A realm holding no copies of the package, with `console.warn` captured.
+ *
+ * The guard keeps its bookkeeping on `globalThis` and its per-copy state in module scope, so a
+ * spec has to control both: the global keys are saved and cleared here, and every copy is
+ * loaded fresh through {@link loadCopy}.
+ */
+export class a_realm {
+    /** Every diagnostic written while this realm is in scope. */
+    readonly warnings: string[] = [];
+
+    private readonly originalWarn = console.warn;
+    private readonly savedInstances = globals[loadedInstancesKey];
+    private readonly savedReported = globals[duplicateReportedKey];
+
+    constructor() {
+        delete globals[loadedInstancesKey];
+        delete globals[duplicateReportedKey];
+        console.warn = (...values: unknown[]) => { this.warnings.push(values.join(' ')); };
+    }
+
+    /**
+     * Loads a copy of the package with its own module scope, the way a package manager
+     * produces one by nesting a second physical install.
+     *
+     * Each call resolves a distinct module identifier, because a module that resolves to an
+     * identifier already in the graph is returned from cache rather than evaluated again - and
+     * an evaluation is exactly what a second copy is. The counter is module scope shared by
+     * every spec file, so identifiers stay distinct across the whole run.
+     *
+     * `@vite-ignore` keeps the identifier out of Vite's dynamic-import-vars pass, which would
+     * otherwise try to resolve the variable part by globbing the file system and fail: the
+     * variation here is in the query, not in the path.
+     * @returns {Promise<PackageCopy>} A copy that has not registered itself yet.
+     */
+    async loadCopy(): Promise<PackageCopy> {
+        copiesLoaded++;
+        return await import(/* @vite-ignore */ `../../duplicateInstanceGuard?copy=${copiesLoaded}`) as PackageCopy;
+    }
+
+    /** Puts back everything the realm took over, so the next spec file starts from the real state. */
+    release() {
+        console.warn = this.originalWarn;
+        globals[loadedInstancesKey] = this.savedInstances;
+        globals[duplicateReportedKey] = this.savedReported;
+    }
+}

package/for_duplicateInstanceGuard/when_a_second_copy_is_loaded.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 { a_realm } from './given/a_realm';
+
+describe('when a second copy is loaded', () => {
+    let realm: a_realm;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+        (await realm.loadCopy()).registerModuleInstance();
+        (await realm.loadCopy()).registerModuleInstance();
+    });
+
+    afterEach(() => realm.release());
+
+    it('should warn exactly once', () => realm.warnings.length.should.equal(1));
+    it('should name the package', () => realm.warnings[0].should.contain('@cratis/fundamentals'));
+    it('should say how many times it was loaded', () => realm.warnings[0].should.contain('Loaded 2 times'));
+    it('should say a registered converter reaches only one copy', () => realm.warnings[0].should.contain('reaches only the copy it was registered on'));
+    it('should say instanceof breaks across the copies', () => realm.warnings[0].should.contain('instanceof against the other copy'));
+    it('should say a top level pin does not reach the nested copy', () => realm.warnings[0].should.contain('does not reach a copy nested under a dependency'));
+    it('should say how to collapse two installs', () => realm.warnings[0].should.contain('yarn dedupe @cratis/fundamentals'));
+    it('should say that dedupe is the wrong answer for one install loaded as both formats', () => realm.warnings[0].should.contain('no dedupe will fix'));
+    it('should name where the first copy was loaded from', () => realm.warnings[0].should.contain('  1. '));
+    it('should name where the second copy was loaded from', () => realm.warnings[0].should.contain('  2. '));
+    it('should locate the copies rather than give up on the stack', () => realm.warnings[0].should.not.contain('unknown location'));
+});

package/for_duplicateInstanceGuard/when_a_third_copy_is_loaded.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_realm } from './given/a_realm';
+
+describe('when a third copy is loaded', () => {
+    let realm: a_realm;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+        (await realm.loadCopy()).registerModuleInstance();
+        (await realm.loadCopy()).registerModuleInstance();
+        (await realm.loadCopy()).registerModuleInstance();
+    });
+
+    afterEach(() => realm.release());
+
+    it('should still warn exactly once', () => realm.warnings.length.should.equal(1));
+    it('should report the count it knew when it warned', () => realm.warnings[0].should.contain('Loaded 2 times'));
+});

package/for_duplicateInstanceGuard/when_checking_the_package_manifest.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.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The guard registers each copy as a load-bearing side effect at module scope, so a bundler must never be told
+// it is free to drop it. Declaring `"sideEffects": false` is the one manifest change that would disable
+// duplicate detection without breaking anything: no build fails, no other spec notices, and a duplicated
+// package quietly goes back to being invisible - which is the failure the guard exists to make visible.
+//
+// duplicateInstanceGuard.ts asks for this in a comment. A comment does not survive a dependency bump or a
+// bundle-size pass, so this is what actually holds the line.
+describe('when checking the package manifest', () => {
+    const manifest = JSON.parse(
+        readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8')) as {
+            sideEffects?: unknown;
+        };
+
+    // Absent is correct: a bundler then treats the package as side-effectful. An explicit `true` is fine too.
+    // Only `false` is the problem, so only `false` is rejected.
+    const declaresNoSideEffects = manifest.sideEffects === false;
+
+    it('should not declare the package free of side effects', () => declaresNoSideEffects.should.be.false);
+});

package/for_duplicateInstanceGuard/when_one_copy_is_loaded.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_realm } from './given/a_realm';
+
+describe('when one copy is loaded', () => {
+    let realm: a_realm;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+        (await realm.loadCopy()).registerModuleInstance();
+    });
+
+    afterEach(() => realm.release());
+
+    it('should not warn', () => realm.warnings.should.be.empty);
+});

package/for_duplicateInstanceGuard/when_one_copy_registers_more_than_once.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_realm } from './given/a_realm';
+
+describe('when one copy registers more than once', () => {
+    let realm: a_realm;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+        const copy = await realm.loadCopy();
+        copy.registerModuleInstance();
+        copy.registerModuleInstance();
+        copy.registerModuleInstance();
+    });
+
+    afterEach(() => realm.release());
+
+    it('should not warn', () => realm.warnings.should.be.empty);
+});

package/for_duplicateInstanceGuard/when_something_else_holds_the_global_key.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_realm } from './given/a_realm';
+
+describe('when something else holds the global key', () => {
+    let realm: a_realm;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+
+        // The bookkeeping is a cross-version contract, so a copy of a different version of this package
+        // may have written the key first - in a shape this one does not recognize. Detection has to
+        // survive that rather than take the process down over its own diagnostic.
+        (globalThis as Record<symbol, unknown>)[Symbol.for('@cratis/fundamentals.loadedInstances')] = 'written by something else';
+
+        (await realm.loadCopy()).registerModuleInstance();
+        (await realm.loadCopy()).registerModuleInstance();
+    });
+
+    afterEach(() => realm.release());
+
+    it('should still report the duplicate', () => realm.warnings.length.should.equal(1));
+    it('should count only the copies it registered itself', () => realm.warnings[0].should.contain('Loaded 2 times'));
+});

package/for_duplicateInstanceGuard/when_the_runtime_has_no_console.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { a_realm } from './given/a_realm';
+
+/** A console that is missing the method the report writes to. */
+type ConsoleWithoutWarn = { warn?: (...values: unknown[]) => void };
+
+describe('when the runtime has no console', () => {
+    let realm: a_realm;
+    let error: unknown;
+
+    beforeEach(async () => {
+        realm = new a_realm();
+        (console as unknown as ConsoleWithoutWarn).warn = undefined;
+
+        try {
+            (await realm.loadCopy()).registerModuleInstance();
+            (await realm.loadCopy()).registerModuleInstance();
+        } catch (thrown) {
+            error = thrown;
+        }
+    });
+
+    afterEach(() => realm.release());
+
+    // A diagnostic that takes the process down when it has nowhere to write is worse than the silence
+    // it was added to break.
+    it('should not throw', () => (error === undefined).should.be.true);
+});

package/geospatial/LineString.ts

@@ -2,11 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { Point } from './Point';
+import { typeKey } from '../typeKey';
 
 /**
  * Represents a line string composed of two or more points.
  */
 export class LineString {
+    static readonly [typeKey] = 'LineString';
+
     coordinates!: Point[];
 
     /**

package/geospatial/Point.ts

@@ -2,11 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { field } from '../fieldDecorator';
+import { typeKey } from '../typeKey';
 
 /**
  * Represents a geographic point with longitude and latitude.
  */
 export class Point {
+    static readonly [typeKey] = 'Point';
+
     @field(Number)
     longitude!: number;
 

package/geospatial/Polygon.ts

@@ -2,11 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { LinearRing } from './LinearRing';
+import { typeKey } from '../typeKey';
 
 /**
  * Represents a polygon with an outer shell and optional holes.
  */
 export class Polygon {
+    static readonly [typeKey] = 'Polygon';
+
     shell!: LinearRing;
     holes!: LinearRing[];
 

package/index.ts

@@ -7,13 +7,16 @@ export * from './geospatial';
 export * from './json';
 export * from './Field';
 export * from './Fields';
+export * from './DateOnly';
 export * from './Guid';
 export * from './IEquatable';
 export * from './PropertyAccessor';
 export * from './PropertyAccessorDescriptor';
 export * from './PropertyPathResolverProxyHandler';
+export * from './TimeOnly';
 export * from './TimeSpan';
 export * from './ValueMap';
+export * from './typeKey';
 export * from './fieldDecorator';
 export * from './derivedTypeDecorator';
 export * from './JsonSerializer';

package/json/DateOnlyJsonConverter.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 { DateOnly } from '../DateOnly';
+import { JsonConverter } from './JsonConverter';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * JSON converter for DateOnly type.
+ */
+export class DateOnlyJsonConverter extends JsonConverter<DateOnly> {
+    /** @inheritdoc */
+    get type(): Constructor<DateOnly> {
+        return DateOnly;
+    }
+
+    /** @inheritdoc */
+    read(value: any): DateOnly {
+        return DateOnly.parse(value.toString());
+    }
+
+    /** @inheritdoc */
+    write(value: any): any {
+        return value?.toString() ?? '';
+    }
+}

package/json/JsonConverter.ts

@@ -19,6 +19,11 @@ export abstract class JsonConverter<T = any> {
      * Determines whether the converter can convert the specified type.
      * @param {Constructor} typeToConvert - The type to check.
      * @returns {boolean} True if the converter can convert the type; otherwise, false.
+     * @deprecated Not called by `JsonSerializer` and scheduled for removal in the next major version.
+     * A converter is resolved by the type it declares through {@link type}, which is what this would
+     * answer anyway, so overriding it has no effect - register a converter per type instead. Wiring it
+     * into the lookup is not the plan either: it would force a scan of every converter on the path
+     * taken by every plain object, to serve a case a second registration already covers.
      */
     canConvert(typeToConvert: Constructor): boolean {
         return typeToConvert === this.type;

package/json/TimeOnlyJsonConverter.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 { TimeOnly } from '../TimeOnly';
+import { JsonConverter } from './JsonConverter';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * JSON converter for TimeOnly type.
+ */
+export class TimeOnlyJsonConverter extends JsonConverter<TimeOnly> {
+    /** @inheritdoc */
+    get type(): Constructor<TimeOnly> {
+        return TimeOnly;
+    }
+
+    /** @inheritdoc */
+    read(value: any): TimeOnly {
+        return TimeOnly.parse(value.toString());
+    }
+
+    /** @inheritdoc */
+    write(value: any): any {
+        return value?.toString() ?? '';
+    }
+}

package/json/index.ts

@@ -3,7 +3,9 @@
 
 export * from './JsonConverter';
 export * from './DateJsonConverter';
+export * from './DateOnlyJsonConverter';
 export * from './GuidJsonConverter';
+export * from './TimeOnlyJsonConverter';
 export * from './TimeSpanJsonConverter';
 export * from './PointJsonConverter';
 export * from './LineStringJsonConverter';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/fundamentals",
-    "version": "7.16.7",
+    "version": "7.17.0",
     "description": "",
     "author": "Cratis",
     "license": "MIT",

package/typeKey.ts

@@ -0,0 +1,54 @@
+// 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';
+
+/**
+ * Identifies a type this package converts, by name rather than by the class object itself.
+ *
+ * `JsonSerializer` recognized a type by comparing constructors, which holds until a second copy of this
+ * package is loaded into the same realm - a nested install, or one install reached as both ESM and
+ * CommonJS. Each copy then had its own `Guid`, `ConceptAs` and `ValueMap` class objects and neither
+ * recognized the other's, so a `Guid` crossing that boundary was written as an object rather than a
+ * string, and a concept as `{"value": ...}` rather than its underlying value. Both silently.
+ *
+ * A name survives the boundary where a class object does not: the key is a registered symbol, so every
+ * copy resolves the same one, and the values are plain strings.
+ *
+ * The key is deliberately a symbol rather than a plain static: a string static would appear in
+ * `Object.keys(Guid)` and could be shadowed by an unrelated member of the same name.
+ */
+export const typeKey: unique symbol = Symbol.for('@cratis/fundamentals.typeKey');
+
+/** A type carrying the key. Only this package's own convertible types declare one. */
+type KeyedType = Constructor & { readonly [typeKey]?: string };
+
+/**
+ * Gets the key a type declares itself, ignoring any inherited from a base type.
+ *
+ * Converter lookup uses this, because a key is inherited: a consumer's `class CustomerId extends
+ * ConceptAs<string>` reports `ConceptAs`, and registering a converter under that would take the place
+ * of concept handling for every concept in the application.
+ * @param {Constructor} type The type to read the key from.
+ * @returns {string | undefined} The declared key, or undefined when the type declares none.
+ */
+export const declaredTypeKey = (type: Constructor | undefined): string | undefined =>
+    type && Object.prototype.hasOwnProperty.call(type, typeKey) ? (type as KeyedType)[typeKey] : undefined;
+
+/**
+ * Gets the key a type carries, whether it declares the key or inherits it from a base type.
+ *
+ * This is what makes a concept recognizable across copies: the key is a static, and a static is
+ * inherited through the constructor's prototype chain, so every type deriving from `ConceptAs` reports
+ * `ConceptAs` without anything having to compare class objects.
+ * @param {Constructor} type The type to read the key from.
+ * @returns {string | undefined} The key carried, or undefined when the type carries none.
+ */
+export const typeKeyOf = (type: Constructor | undefined): string | undefined =>
+    type ? (type as KeyedType)[typeKey] : undefined;
+
+/** The key every type deriving from `ConceptAs` carries. */
+export const conceptAsTypeKey = 'ConceptAs';
+
+/** The key `ValueMap` declares. */
+export const valueMapTypeKey = 'ValueMap';