@cratis/fundamentals 7.16.7 → 7.17.0

package/for_DateOnly/when_reading_it_west_of_utc.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 { DateOnly } from '../DateOnly';
+
+/**
+ * The reason this type exists. A calendar date forced into a `Date` becomes UTC midnight, and every browser-local
+ * getter west of UTC then reads it back as the previous day - correct in Europe, wrong in the Americas, which is
+ * how the mistake survives development and reaches users.
+ */
+describe('when reading it west of utc', () => {
+    const dueDate = DateOnly.parse('2026-05-12');
+
+    const asAnInstant = new Date('2026-05-12');
+    const instantWestOfUtc = new Intl.DateTimeFormat('en-CA', { timeZone: 'America/New_York' }).format(asAnInstant);
+
+    it('should be the day the server sent, whatever zone reads it', () => dueDate.toString().should.equal('2026-05-12'));
+
+    // Pins the behavior being avoided, so the reason for the type cannot quietly stop being true.
+    it('should not be what an instant would have rendered as', () => instantWestOfUtc.should.equal('2026-05-11'));
+
+    it('should keep the day when a local Date is asked for', () => dueDate.toDate().getDate().should.equal(12));
+    it('should keep the month when a local Date is asked for', () => (dueDate.toDate().getMonth() + 1).should.equal(5));
+});

package/for_JsonSerializer/RegisteredConverterTypes.ts

@@ -0,0 +1,45 @@
+// 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 { JsonConverter } from '../json';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * A domain type the package knows nothing about, standing in for the type a consumer needs to put on
+ * the wire in a shape only they can decide.
+ */
+export class Temperature {
+    constructor(readonly celsius: number) {}
+}
+
+/** Puts a {@link Temperature} on the wire as the string a consumer chose. */
+export class TemperatureJsonConverter extends JsonConverter<Temperature> {
+    get type(): Constructor<Temperature> {
+        return Temperature;
+    }
+
+    read(value: any): Temperature {
+        return new Temperature(Number(String(value).replace('C', '')));
+    }
+
+    write(value: Temperature): any {
+        return `${value.celsius}C`;
+    }
+}
+
+/** A second, disagreeing converter for the same type, for pinning what a re-registration does. */
+export class TemperatureInFahrenheitJsonConverter extends JsonConverter<Temperature> {
+    get type(): Constructor<Temperature> {
+        return Temperature;
+    }
+
+    read(value: any): Temperature {
+        return new Temperature((Number(String(value).replace('F', '')) - 32) / 1.8);
+    }
+
+    write(value: Temperature): any {
+        return `${(value.celsius * 1.8) + 32}F`;
+    }
+}

package/for_JsonSerializer/when_a_converter_is_registered_for_a_concept.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs } from '../ConceptAs';
+import { Constructor } from '../Constructor';
+import { JsonSerializer } from '../JsonSerializer';
+import { JsonConverter } from '../json';
+import { field } from '../fieldDecorator';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+class Reference extends ConceptAs<string> {}
+
+/** Registered for the concept itself, which is the thing that does not reach it. */
+class ReferenceJsonConverter extends JsonConverter<Reference> {
+    get type(): Constructor<Reference> {
+        return Reference;
+    }
+
+    read(): Reference {
+        return new Reference('read-by-converter');
+    }
+
+    write(): any {
+        return 'written-by-converter';
+    }
+}
+
+class Document {
+    @field(Reference)
+    reference!: Reference;
+}
+
+describe('when a converter is registered for a concept', () => {
+    JsonSerializer.registerConverter(new ReferenceJsonConverter());
+
+    const document = new Document();
+    document.reference = new Reference('the-underlying-value');
+
+    const serialized = JSON.parse(JsonSerializer.serialize(document));
+    const deserialized = JsonSerializer.deserialize(Document, '{"reference":"the-underlying-value"}');
+
+    it('should unwrap the concept rather than reach the converter on the way out', () => serialized.reference.should.equal('the-underlying-value'));
+    it('should rebuild the concept rather than reach the converter on the way in', () => deserialized.reference.value.should.equal('the-underlying-value'));
+    it('should still produce the concept type', () => deserialized.reference.should.be.instanceof(Reference));
+});

package/for_JsonSerializer/when_a_converter_is_registered_for_a_type_that_already_has_one.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 { JsonSerializer } from '../JsonSerializer';
+import { field } from '../fieldDecorator';
+import { Temperature, TemperatureJsonConverter, TemperatureInFahrenheitJsonConverter } from './RegisteredConverterTypes';
+
+class Reading {
+    @field(Temperature)
+    temperature!: Temperature;
+}
+
+describe('when a converter is registered for a type that already has one', () => {
+    JsonSerializer.registerConverter(new TemperatureJsonConverter());
+    JsonSerializer.registerConverter(new TemperatureInFahrenheitJsonConverter());
+
+    const reading = new Reading();
+    reading.temperature = new Temperature(100);
+
+    const serialized = JSON.parse(JsonSerializer.serialize(reading));
+    const deserialized = JsonSerializer.deserialize(Reading, '{"temperature":"32F"}');
+
+    it('should serialize through the converter registered last', () => serialized.temperature.should.equal('212F'));
+    it('should deserialize through the converter registered last', () => deserialized.temperature.celsius.should.equal(0));
+});

package/for_JsonSerializer/when_a_converter_is_registered_for_a_type_the_package_already_converts.ts

@@ -0,0 +1,51 @@
+// 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 { JsonSerializer } from '../JsonSerializer';
+import { DateJsonConverter, JsonConverter } from '../json';
+import { field } from '../fieldDecorator';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Writes a Date as a calendar day rather than an instant - the shape a consumer reaches for when a
+ * value that is a date on the wire keeps arriving as UTC midnight and rendering a day early.
+ */
+class CalendarDateJsonConverter extends JsonConverter<Date> {
+    get type(): Constructor<Date> {
+        return Date;
+    }
+
+    read(value: any): Date {
+        return new Date(`${value}T00:00:00`);
+    }
+
+    write(value: Date): any {
+        return value.toISOString().substring(0, 10);
+    }
+}
+
+class Booking {
+    @field(Date)
+    arrivesOn!: Date;
+}
+
+describe('when a converter is registered for a type the package already converts', () => {
+    const booking = new Booking();
+    booking.arrivesOn = new Date(Date.UTC(2026, 7, 4, 9, 30));
+
+    const beforeRegistering = JSON.parse(JsonSerializer.serialize(booking));
+
+    JsonSerializer.registerConverter(new CalendarDateJsonConverter());
+    const afterRegistering = JSON.parse(JsonSerializer.serialize(booking));
+
+    // Put the built-in back before any assertion runs, so a failing expectation cannot leave the
+    // registry - which is module scope shared by every spec file - holding this spec's converter.
+    JsonSerializer.registerConverter(new DateJsonConverter());
+    const afterRestoring = JSON.parse(JsonSerializer.serialize(booking));
+
+    it('should use the built-in converter until one is registered', () => beforeRegistering.arrivesOn.should.equal('2026-08-04T09:30:00.000Z'));
+    it('should take the place of the built-in converter', () => afterRegistering.arrivesOn.should.equal('2026-08-04'));
+    it('should hand back to a built-in converter registered after it', () => afterRestoring.arrivesOn.should.equal('2026-08-04T09:30:00.000Z'));
+});

package/for_JsonSerializer/when_a_converter_is_registered_for_a_value_map.ts

@@ -0,0 +1,49 @@
+// 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 { JsonSerializer } from '../JsonSerializer';
+import { ValueMap } from '../ValueMap';
+import { JsonConverter, ValueMapJsonConverter } from '../json';
+import { field } from '../fieldDecorator';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+class CountingValueMapJsonConverter extends JsonConverter<ValueMap<any, any>> {
+    get type(): Constructor<ValueMap<any, any>> {
+        return ValueMap;
+    }
+
+    read(): ValueMap<any, any> {
+        return new ValueMap<any, any>().set('read-by', 'converter');
+    }
+
+    write(): any {
+        return 'written-by-converter';
+    }
+}
+
+class Holder {
+    @field(ValueMap, { genericArguments: [String, String] })
+    entries!: ValueMap<string, string>;
+}
+
+describe('when a converter is registered for a value map', () => {
+    const holder = new Holder();
+    holder.entries = new ValueMap<string, string>().set('a', 'b');
+
+    JsonSerializer.registerConverter(new CountingValueMapJsonConverter());
+    const serialized = JSON.parse(JsonSerializer.serialize(holder));
+    const deserialized = JsonSerializer.deserialize(Holder, '{"entries":{"a":"b"}}');
+
+    // Put the built-in back before any assertion runs. Writing a ValueMap does go through the
+    // registered converter, so leaving this one in place would change every later spec that
+    // serializes one.
+    JsonSerializer.registerConverter(new ValueMapJsonConverter());
+
+    const deserializedKeys = [...deserialized.entries.entries()].map(entry => entry[0]);
+
+    it('should reach the converter on the way out', () => serialized.entries.should.equal('written-by-converter'));
+    it('should not reach the converter on the way in', () => deserializedKeys.should.not.contain('read-by'));
+    it('should read the field back from the payload instead', () => deserializedKeys.should.deep.equal(['a']));
+});

package/for_JsonSerializer/when_a_converter_is_registered_for_an_unknown_type.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 { JsonSerializer } from '../JsonSerializer';
+import { field } from '../fieldDecorator';
+import { Temperature, TemperatureJsonConverter } from './RegisteredConverterTypes';
+
+class Reading {
+    @field(Temperature)
+    temperature!: Temperature;
+
+    @field(String)
+    station!: string;
+}
+
+describe('when a converter is registered for an unknown type', () => {
+    JsonSerializer.registerConverter(new TemperatureJsonConverter());
+
+    const reading = new Reading();
+    reading.temperature = new Temperature(21.5);
+    reading.station = 'Blindern';
+
+    const serialized = JSON.parse(JsonSerializer.serialize(reading));
+    const deserialized = JsonSerializer.deserialize(Reading, '{"temperature":"18C","station":"Blindern"}');
+
+    it('should serialize through the registered converter', () => serialized.temperature.should.equal('21.5C'));
+    it('should leave the other properties alone', () => serialized.station.should.equal('Blindern'));
+    it('should deserialize through the registered converter', () => deserialized.temperature.should.be.instanceof(Temperature));
+    it('should deserialize to the converted value', () => deserialized.temperature.celsius.should.equal(18));
+});

package/for_JsonSerializer/when_a_type_comes_from_another_copy_of_the_package.ts

@@ -0,0 +1,63 @@
+// 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 { Fields } from '../Fields';
+import { JsonSerializer } from '../JsonSerializer';
+
+/**
+ * Loads a module with its own scope, standing in for the second copy of the package a nested install
+ * or a dual ESM/CommonJS load produces. A distinct identifier is evaluated rather than served from
+ * cache, and an evaluation is what makes the class objects distinct - which is the whole problem.
+ *
+ * `@vite-ignore` keeps the identifier away from Vite's dynamic-import-vars pass, which would try to
+ * resolve the variation by globbing the file system: the variation is in the query, not the path.
+ */
+const anotherCopyOf = async <TModule>(module: string): Promise<TModule> =>
+    await import(/* @vite-ignore */ `../${module}?anotherCopy`) as TModule;
+
+describe('when a type comes from another copy of the package', () => {
+    let serializedGuid: { id: string };
+    let serializedConcept: { reference: string };
+    let deserializedConcept: { value: string };
+    let deserializedValueMapKeys: unknown[];
+    let guidClassIsDistinct: boolean;
+    let conceptBaseIsDistinct: boolean;
+
+    beforeEach(async () => {
+        const thisCopyGuid = await import('../Guid');
+        const otherGuid = await anotherCopyOf<typeof thisCopyGuid>('Guid');
+        const thisCopyConceptAs = await import('../ConceptAs');
+        const otherConceptAs = await anotherCopyOf<typeof thisCopyConceptAs>('ConceptAs');
+        const otherValueMap = await anotherCopyOf<typeof import('../ValueMap')>('ValueMap');
+
+        guidClassIsDistinct = thisCopyGuid.Guid !== otherGuid.Guid;
+        conceptBaseIsDistinct = thisCopyConceptAs.ConceptAs !== otherConceptAs.ConceptAs;
+
+        class Reference extends otherConceptAs.ConceptAs<string> {}
+
+        class Holder {
+            reference!: unknown;
+            entries!: unknown;
+        }
+
+        Fields.addFieldToType(Holder, 'reference', Reference as unknown as Constructor, false, [], []);
+        Fields.addFieldToType(Holder, 'entries', otherValueMap.ValueMap, false, [], [String, String]);
+
+        serializedGuid = JSON.parse(JsonSerializer.serialize({ id: otherGuid.Guid.parse('a1b2c3d4-1111-2222-3333-444455556666') }));
+        serializedConcept = JSON.parse(JsonSerializer.serialize({ reference: new Reference('the-value') }));
+
+        const holder = JsonSerializer.deserialize(Holder, '{"reference":"the-value","entries":{"a":"b"}}');
+        deserializedConcept = holder.reference as { value: string };
+        const entries = holder.entries as InstanceType<typeof otherValueMap.ValueMap>;
+        deserializedValueMapKeys = [...entries.entries()].map(entry => entry[0]);
+    });
+
+    it('should be a genuinely different Guid class', () => guidClassIsDistinct.should.be.true);
+    it('should be a genuinely different ConceptAs base', () => conceptBaseIsDistinct.should.be.true);
+
+    it('should write the other copy\'s Guid as a string', () => serializedGuid.id.should.equal('a1b2c3d4-1111-2222-3333-444455556666'));
+    it('should unwrap a concept deriving from the other copy\'s ConceptAs', () => serializedConcept.reference.should.equal('the-value'));
+    it('should rebuild a concept deriving from the other copy\'s ConceptAs', () => deserializedConcept.value.should.equal('the-value'));
+    it('should read the other copy\'s ValueMap from its generic arguments', () => deserializedValueMapKeys.should.deep.equal(['a']));
+});

package/for_JsonSerializer/when_deserializing_object_with_absent_collection.ts

@@ -0,0 +1,36 @@
+// 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';
+import { JsonSerializer } from '../JsonSerializer';
+
+
+class TheType {
+    @field(String)
+    someString!: string;
+
+    @field(String, true)
+    someCollection!: string[];
+
+    @field(String, true)
+    someNullCollection!: string[];
+}
+
+const json = '{' +
+    '    "someString": "forty two",' +
+    '    "someNullCollection": null' +
+    '}';
+
+describe('when deserializing object with absent collection', () => {
+    const result = JsonSerializer.deserialize(TheType, json);
+
+    it('should hold the value that was there', () => result.someString.should.equal('forty two'));
+
+    // The declared type says this is an array. A producer that leaves an empty collection out of the payload
+    // would otherwise hand back undefined behind that type, so every reader has to guard it.
+    it('should give the absent collection an empty array', () => result.someCollection.should.be.an('array'));
+    it('should give the absent collection no items', () => result.someCollection.length.should.equal(0));
+
+    // An explicit null is the producer saying "no collection", which is not the same as an empty one.
+    it('should leave an explicit null alone', () => expect(result.someNullCollection).to.be.null);
+});

package/for_JsonSerializer/when_deserializing_temporal_values.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 { DateOnly } from '../DateOnly';
+import { field } from '../fieldDecorator';
+import { JsonSerializer } from '../JsonSerializer';
+import { TimeOnly } from '../TimeOnly';
+
+class Appointment {
+    @field(DateOnly)
+    on!: DateOnly;
+
+    @field(TimeOnly)
+    at!: TimeOnly;
+}
+
+/**
+ * The end of the chain the types exist for: what the server sends has to arrive as the value it names, through the
+ * registered converters, without anyone at the call site parsing anything.
+ */
+describe('when deserializing temporal values', () => {
+    const deserialized = JsonSerializer.deserializeFromInstance(Appointment, { on: '2026-05-12', at: '14:30:45' });
+
+    it('should deserialize the date as a DateOnly', () => (deserialized.on instanceof DateOnly).should.be.true);
+    it('should deserialize the time as a TimeOnly', () => (deserialized.at instanceof TimeOnly).should.be.true);
+    it('should keep the calendar date', () => deserialized.on.toString().should.equal('2026-05-12'));
+    it('should keep the time of day', () => deserialized.at.toString().should.equal('14:30:45'));
+
+    it('should serialize back to what the server sent', () =>
+        JSON.parse(JsonSerializer.serialize(deserialized)).should.deep.equal({ on: '2026-05-12', at: '14:30:45' }));
+});

package/for_JsonSerializer/when_metadata_is_written_by_another_copy_of_the_package.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DerivedType } from '../DerivedType';
+import { Fields } from '../Fields';
+
+/**
+ * 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.)
+ *
+ * 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.
+ */
+describe('when metadata is written by another copy of the package', () => {
+    let fieldsAreDistinct: boolean;
+    let derivedTypeIsDistinct: boolean;
+    let fieldNamesReadByTheOtherCopy: string[];
+    let derivedTypeReadByTheOtherCopy: string | undefined;
+
+    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');
+
+        fieldsAreDistinct = Fields !== otherFields.Fields;
+        derivedTypeIsDistinct = DerivedType !== otherDerivedType.DerivedType;
+
+        class Subject { }
+
+        Fields.addFieldToType(Subject, 'name', String, false, [], []);
+        DerivedType.set(Subject, 'an-identifier');
+
+        fieldNamesReadByTheOtherCopy = otherFields.Fields.getFieldsForType(Subject).map(_ => _.name);
+        derivedTypeReadByTheOtherCopy = otherDerivedType.DerivedType.get(Subject);
+    });
+
+    it('should be a genuinely different Fields', () => fieldsAreDistinct.should.be.true);
+    it('should be a genuinely different DerivedType', () => derivedTypeIsDistinct.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'));
+});

package/for_JsonSerializer/when_no_converter_is_registered_for_a_type.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { JsonSerializer } from '../JsonSerializer';
+import { field } from '../fieldDecorator';
+
+class Coordinates {
+    @field(Number)
+    latitude!: number;
+
+    @field(Number)
+    longitude!: number;
+}
+
+class Site {
+    @field(Coordinates)
+    coordinates!: Coordinates;
+}
+
+describe('when no converter is registered for a type', () => {
+    const site = new Site();
+    site.coordinates = new Coordinates();
+    site.coordinates.latitude = 59.94;
+    site.coordinates.longitude = 10.72;
+
+    const serialized = JSON.parse(JsonSerializer.serialize(site));
+    const deserialized = JsonSerializer.deserialize(Site, '{"coordinates":{"latitude":59.94,"longitude":10.72}}');
+
+    it('should serialize it property by property as before', () => serialized.coordinates.should.deep.equal({ latitude: 59.94, longitude: 10.72 }));
+    it('should deserialize it to the declared type', () => deserialized.coordinates.should.be.instanceof(Coordinates));
+    it('should deserialize its properties', () => deserialized.coordinates.latitude.should.equal(59.94));
+});

package/for_JsonSerializer/when_round_tripping_a_value_map_of_primitive_values.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { JsonSerializer } from '../JsonSerializer';
+import { ValueMap } from '../ValueMap';
+import { field } from '../fieldDecorator';
+
+class Settings {
+    @field(ValueMap, { genericArguments: [String, String] })
+    text!: ValueMap<string, string>;
+
+    @field(ValueMap, { genericArguments: [String, Number] })
+    numbers!: ValueMap<string, number>;
+
+    @field(ValueMap, { genericArguments: [String, Boolean] })
+    flags!: ValueMap<string, boolean>;
+}
+
+describe('when round tripping a value map of primitive values', () => {
+    const settings = new Settings();
+    settings.text = new ValueMap<string, string>().set('greeting', 'hello');
+    settings.numbers = new ValueMap<string, number>().set('retries', 3);
+    settings.flags = new ValueMap<string, boolean>().set('enabled', true);
+
+    const written = JsonSerializer.serialize(settings);
+    const read = JsonSerializer.deserialize(Settings, written);
+
+    it('should write the values as the primitives they are', () => written.should.equal('{"text":{"greeting":"hello"},"numbers":{"retries":3},"flags":{"enabled":true}}'));
+    it('should read a string value back as a string', () => read.text.get('greeting')!.should.equal('hello'));
+    it('should read a number value back as a number', () => read.numbers.get('retries')!.should.equal(3));
+    it('should read a boolean value back as a boolean', () => read.flags.get('enabled')!.should.equal(true));
+    it('should read a string value back as a primitive rather than a String object', () => (typeof read.text.get('greeting')).should.equal('string'));
+    it('should read a number value back as a primitive rather than a Number object', () => (typeof read.numbers.get('retries')).should.equal('number'));
+    it('should read a boolean value back as a primitive rather than a Boolean object', () => (typeof read.flags.get('enabled')).should.equal('boolean'));
+});

package/for_JsonSerializer/when_round_tripping_concepts_outside_a_declared_field.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 { ConceptAs } from '../ConceptAs';
+import { JsonSerializer } from '../JsonSerializer';
+import { ValueMap } from '../ValueMap';
+import { field } from '../fieldDecorator';
+
+class Tag extends ConceptAs<string> {}
+
+class Article {
+    @field(Tag)
+    primaryTag!: Tag;
+
+    @field(Tag, true)
+    tags!: Tag[];
+
+    @field(ValueMap, { genericArguments: [String, Tag] })
+    tagBySection!: ValueMap<string, Tag>;
+}
+
+describe('when round tripping concepts outside a declared field', () => {
+    const article = new Article();
+    article.primaryTag = new Tag('news');
+    article.tags = [new Tag('sport'), new Tag('weather')];
+    article.tagBySection = new ValueMap<string, Tag>().set('front', new Tag('lead'));
+
+    const written = JsonSerializer.serialize(article);
+    const read = JsonSerializer.deserialize(Article, written);
+
+    it('should write a concept in a collection as its underlying value', () => written.should.contain('"tags":["sport","weather"]'));
+    it('should write a concept in a value map as its underlying value', () => written.should.contain('"tagBySection":{"front":"lead"}'));
+    it('should write a concept in a declared field as its underlying value', () => written.should.contain('"primaryTag":"news"'));
+
+    it('should read a collection back as concepts', () => read.tags.map(_ => _.value).should.deep.equal(['sport', 'weather']));
+    it('should read a collection element back as the concept type', () => read.tags[0].should.be.instanceof(Tag));
+    it('should read a value map value back as a concept', () => read.tagBySection.get('front')!.value.should.equal('lead'));
+    it('should read a value map value back as the concept type', () => read.tagBySection.get('front')!.should.be.instanceof(Tag));
+});

package/for_TimeOnly/when_parsing_a_time_of_day.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 { TimeOnly } from '../TimeOnly';
+
+describe('when parsing a time of day', () => {
+    const parsed = TimeOnly.parse('14:30:45');
+
+    it('should have the hour', () => parsed.hour.should.equal(14));
+    it('should have the minute', () => parsed.minute.should.equal(30));
+    it('should have the second', () => parsed.second.should.equal(45));
+    it('should render back to what it was parsed from', () => parsed.toString().should.equal('14:30:45'));
+
+    // A Date needs a date, and a time of day has none - so this is destroyed outright rather than shifted, which
+    // is the starker of the two temporal cases and the reason the type is not a Date.
+    it('should not be something a Date could have held', () => isNaN(new Date('14:30:45').getTime()).should.be.true);
+});

package/for_TimeOnly/when_parsing_the_shapes_the_server_sends.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 { TimeOnly } from '../TimeOnly';
+
+/**
+ * The server omits the seconds and the fraction when they are zero, and writes up to seven fractional digits where
+ * JavaScript holds three. Every one of those shapes has to parse, and a value has to survive a parse followed by a
+ * render without moving.
+ */
+describe('when parsing the shapes the server sends', () => {
+    const withoutSeconds = TimeOnly.parse('14:30');
+    const withFraction = TimeOnly.parse('14:30:45.1234567');
+    const midnight = TimeOnly.parse('00:00:00');
+
+    it('should default the seconds when they are omitted', () => withoutSeconds.second.should.equal(0));
+    it('should render omitted seconds explicitly', () => withoutSeconds.toString().should.equal('14:30:00'));
+
+    // Truncated rather than rounded, so a parse followed by a render never moves the value forward.
+    it('should truncate the fraction to milliseconds', () => withFraction.millisecond.should.equal(123));
+    it('should render the fraction it kept', () => withFraction.toString().should.equal('14:30:45.123'));
+
+    it('should parse midnight', () => midnight.toString().should.equal('00:00:00'));
+});