@coast/core-utils 0.0.24 → 0.0.28

package/src/AssertionUtils.ts

@@ -1,10 +1,7 @@
-import { EntityType } from '@coast/core-types/common/EntityType';
 import { GeneralErrorCode } from '@coast/core-types/error/GeneralErrorCode';
 import { AssertionFailedException } from '@coast/core-types/exception/AssertionFailedException';
 import { CoastException } from '@coast/core-types/exception/CoastException';
-import { InvalidEntityReferenceException } from '@coast/core-types/exception/InvalidEntityReferenceException';
 import { NotDefinedException } from '@coast/core-types/exception/NotDefinedException';
-import { NotFoundException } from '@coast/core-types/exception/NotFoundException';
 import { DeepLogObject } from '@coast/service-common/logger/DeepLogObject';
 import _ from 'lodash';
 import nodeAssert from 'node:assert';
@@ -19,36 +16,6 @@ export class AssertionUtils {
         }
     }
 
-    public static assertValidEntityReference<T extends object>(
-        entity: T | null | undefined,
-        entityType: EntityType,
-        options: { id?: string; message?: string } = {}
-    ): asserts entity is T {
-        AssertionUtils.assertIsDefined(
-            entity,
-            new InvalidEntityReferenceException({
-                entityType,
-                id: options?.id,
-                message: options?.message,
-            })
-        );
-    }
-
-    public static assertEntityFound<T extends object>(
-        entity: T | null | undefined,
-        entityType: EntityType,
-        options: { id?: string; message?: string } = {}
-    ): asserts entity is T {
-        AssertionUtils.assertIsDefined(
-            entity,
-            new NotFoundException({
-                entityType,
-                id: options?.id,
-                message: options?.message,
-            })
-        );
-    }
-
     public static assert(value: unknown, error?: CoastException | string): asserts value {
         try {
             nodeAssert(value); // eslint-disable-line @typescript-eslint/strict-boolean-expressions

package/src/CompactSet.ts

@@ -0,0 +1,31 @@
+/**
+ * CompactSet is a typical Set but ignores null and undefined
+ */
+export class CompactSet<T = unknown> extends Set<T> {
+    /**
+     * Null and undefined values will be ingnored
+     * (new CompactSet()).add(null).add(undefined).size // 0
+     */
+    public add(value: T | null | undefined): this {
+        if (value === undefined || value === null) {
+            return this;
+        }
+        super.add(value);
+
+        return this;
+    }
+
+    /**
+     * Convenience method to add all items in an array to this set
+     * Handles null, undefined and empty arrays gracefully
+     */
+    public addAll(values: Array<T | null | undefined> | null | undefined): this {
+        values?.forEach((value: T | null | undefined) => this.add(value));
+
+        return this;
+    }
+
+    public asArray(): T[] {
+        return Array.from(this);
+    }
+}

package/src/EntityRehydrator.ts

@@ -0,0 +1,35 @@
+import { EntityIdMap } from '@coast/core-types/common/EntityIdMap';
+import { EntityType } from '@coast/core-types/common/EntityType';
+import { EntityTypeLabels } from '@coast/core-types/common/EntityTypeLabels';
+import { CoastLogger } from '@coast/service-common/logger/CoastLogger';
+import _ from 'lodash';
+
+export class EntityRehydrator<ET extends EntityType> {
+    public static readonly MISSING_REQUIRED_PROPERTY = 'MISSING_REQUIRED_PROPERTY';
+
+    public constructor(
+        private readonly entityType: ET,
+        private readonly logger?: CoastLogger
+    ) {}
+
+    /**
+     * A read never throws. The row exists either way, and failing it hides every other row in the
+     * same fetch while giving the caller nothing it can act on, so a property the stored row left
+     * out is narrowed and reported rather than rejected.
+     */
+    public require<T extends { id: EntityIdMap[ET] }, K extends keyof T>(entity: T, propertyName: K): NonNullable<T[K]> {
+        const value = entity[propertyName];
+
+        if (_.isNil(value)) {
+            this.logger?.warn({
+                msg: `${EntityTypeLabels[this.entityType]} is missing required property ${String(propertyName)}`,
+                event: EntityRehydrator.MISSING_REQUIRED_PROPERTY,
+                entityType: this.entityType,
+                propertyName: String(propertyName),
+                id: _.isNil(entity.id) ? undefined : String(entity.id),
+            });
+        }
+
+        return value as NonNullable<T[K]>;
+    }
+}

package/src/EntityUtils.ts

@@ -0,0 +1,37 @@
+import { EntityType } from '@coast/core-types/common/EntityType';
+import { InvalidEntityReferenceException } from '@coast/core-types/exception/InvalidEntityReferenceException';
+import { NotFoundException } from '@coast/core-types/exception/NotFoundException';
+
+import { AssertionUtils } from './AssertionUtils';
+
+export class EntityUtils {
+    public static assertValidEntityReference<T extends object>(
+        entity: T | null | undefined,
+        entityType: EntityType,
+        options: { id?: string; message?: string } = {}
+    ): asserts entity is T {
+        AssertionUtils.assertIsDefined(
+            entity,
+            new InvalidEntityReferenceException({
+                entityType,
+                id: options?.id,
+                message: options?.message,
+            })
+        );
+    }
+
+    public static assertEntityFound<T extends object>(
+        entity: T | null | undefined,
+        entityType: EntityType,
+        options: { id?: string; message?: string } = {}
+    ): asserts entity is T {
+        AssertionUtils.assertIsDefined(
+            entity,
+            new NotFoundException({
+                entityType,
+                id: options?.id,
+                message: options?.message,
+            })
+        );
+    }
+}

package/src/ISODateStringUtils.ts

@@ -0,0 +1,24 @@
+import { ISODateString } from '@coast/core-types/common/ISODateString';
+
+/**
+ * Conversions between a DTO `Date` and the `ISODateString` stored in a JSON column.
+ *
+ * A JSON column is unvalidated, so a field typed `Date` may hold any string a past write left
+ * there. Neither direction throws and neither normalizes: an unparseable value is carried through
+ * unchanged in both directions, so a read-modify-write writes the original bytes back. The cast is
+ * the cost — an unparseable stored value surfaces as a string typed `Date`, exactly as every
+ * strangler-read date does today — and it is confined to this class.
+ */
+export class ISODateStringUtils {
+    public static fromDate(value: Date): ISODateString {
+        const parsed = new Date(value);
+
+        return Number.isNaN(parsed.getTime()) ? (value as unknown as ISODateString) : ISODateString(parsed.toISOString());
+    }
+
+    public static toDate(value: ISODateString): Date {
+        const parsed = new Date(value);
+
+        return Number.isNaN(parsed.getTime()) ? (value as unknown as Date) : parsed;
+    }
+}

package/src/JsonPath.ts

@@ -0,0 +1,58 @@
+export class JsonPath {
+    public constructor(public readonly value: string) {}
+
+    /**
+     * Converts a dot-notation path string into a properly formatted JsonPath.
+     * Handles paths that may need bracket notation for special characters or numbers.
+     * Produces RFC 9535 compliant JSONPath syntax.
+     */
+    public static fromString(path: string): JsonPath {
+        if (path.startsWith('$')) {
+            return new JsonPath(path);
+        }
+
+        const segments = path.split('.');
+
+        const formattedPath = segments
+            .map((segment, index) => {
+                const isFirstSegment = index === 0;
+                const requiresBrackets = this.needsBracketNotation(segment);
+
+                if (isFirstSegment) {
+                    return requiresBrackets ? `$['${segment}']` : `$.${segment}`;
+                }
+
+                return requiresBrackets ? `['${segment}']` : `.${segment}`;
+            })
+            .join('');
+
+        return new JsonPath(formattedPath);
+    }
+
+    /**
+     * Determines if a path segment requires bracket notation.
+     * Returns true if the segment:
+     * 1. Starts with a number
+     * 2. Contains special characters (anything other than alphanumeric and underscore)
+     *
+     * Note: UUIDs are automatically handled by condition #2 since they contain hyphens.
+     */
+    private static needsBracketNotation(segment: string): boolean {
+        return /^\d/.test(segment) || /\W/.test(segment);
+    }
+
+    /**
+     * Appends a path to the current path.
+     * If a string is provided, it will be converted to a JsonPath first.
+     */
+    public appendPath(path: JsonPath | string): JsonPath {
+        const pathToAppend = path instanceof JsonPath ? path : JsonPath.fromString(path);
+        const appendValue = pathToAppend.value.replace('$', '');
+
+        return new JsonPath(`${this.value}${appendValue}`);
+    }
+
+    public toString(): string {
+        return this.value;
+    }
+}

package/src/ObjectUtils.ts

@@ -1,3 +1,5 @@
+import { Patch } from '@coast/core-types/utils/Patch';
+import { WithNullable } from '@coast/core-types/utils/WithNullable';
 import _ from 'lodash';
 
 import { DeepPartial } from './DeepPartial';
@@ -27,6 +29,33 @@ export class ObjectUtils {
         return { ...target, ...cleanSource };
     }
 
+    /**
+     * Applies a `Patch` to `original`, returning the exhaustive next value. Per the patch contract:
+     * `undefined` is SKIPPED (keep the original value), `null` CLEARS the property, and any other
+     * value SETS it.
+     */
+    public static applyPatch<T extends object, TImmutableProperties extends keyof T>(
+        original: T,
+        patch: Patch<T, TImmutableProperties>
+    ): T {
+        const appliedEntries = Object.fromEntries(
+            Object.entries(patch)
+                .filter(([_key, value]) => value !== undefined)
+                .map(([key, value]) => [key, value === null ? undefined : value])
+        );
+
+        return { ...original, ...appliedEntries };
+    }
+
+    /**
+     * Shallow-replaces every `undefined` value with `null`.
+     */
+    public static nullifyUndefined<T extends object>(obj: T): WithNullable<T> {
+        return Object.fromEntries(
+            Object.entries(obj).map(([key, value]) => [key, value === undefined ? null : value])
+        ) as WithNullable<T>;
+    }
+
     public static getFirstKey<T extends object>(obj: T): keyof T {
         return Object.keys(obj)[0] as keyof T;
     }

package/src/test/AssertionUtilsTest.ts

@@ -1,8 +1,5 @@
-import { EntityType } from '@coast/core-types/common/EntityType';
-import { EntityTypeLabels } from '@coast/core-types/common/EntityTypeLabels';
 import { AssertionFailedException } from '@coast/core-types/exception/AssertionFailedException';
 import { CoastException } from '@coast/core-types/exception/CoastException';
-import { InvalidEntityReferenceException } from '@coast/core-types/exception/InvalidEntityReferenceException';
 import { NotDefinedException } from '@coast/core-types/exception/NotDefinedException';
 import { assertType } from '@coast/service-common/types/assertType';
 import { Equals } from '@coast/service-common/types/Equals';
@@ -95,49 +92,4 @@ describe('AssertionUtils', () => {
             assertType<Equals<typeof x, string>>();
         });
     });
-
-    describe('assertValidEntityReference', () => {
-        it('should throw if value is not defined', () => {
-            const x = undefined as object | undefined;
-            try {
-                AssertionUtils.assertValidEntityReference(x, EntityType.WORKFLOW_ENTITY);
-            } catch (error) {
-                expect(error).toBeInstanceOf(InvalidEntityReferenceException);
-
-                safeExpect((error as InvalidEntityReferenceException).message).toEqual(
-                    `Invalid entity reference: ${EntityTypeLabels[EntityType.WORKFLOW_ENTITY]} not found`
-                );
-
-                safeExpect((error as InvalidEntityReferenceException).additionalData).toMatchObject({
-                    entityType: EntityType.WORKFLOW_ENTITY,
-                });
-            }
-        });
-
-        it('should use custom error message', () => {
-            const x = undefined as object | undefined;
-            try {
-                AssertionUtils.assertValidEntityReference(x, EntityType.WORKFLOW_ENTITY, {
-                    message: 'x should exist...',
-                    id: 'abc-123',
-                });
-            } catch (error) {
-                expect(error).toBeInstanceOf(InvalidEntityReferenceException);
-                safeExpect((error as InvalidEntityReferenceException).message).toEqual('x should exist...');
-
-                safeExpect((error as InvalidEntityReferenceException).additionalData).toMatchObject({
-                    entityType: EntityType.WORKFLOW_ENTITY,
-                    id: 'abc-123',
-                });
-            }
-        });
-
-        it('should not throw and should type narrow if value is defined', () => {
-            const x = { id: 'abc' } as object | undefined;
-            assertType<Equals<typeof x, object | undefined>>();
-
-            AssertionUtils.assertValidEntityReference(x, EntityType.COMPONENT);
-            assertType<Equals<typeof x, object>>();
-        });
-    });
 });

package/src/test/CompactSetTest.ts

@@ -0,0 +1,106 @@
+import { safeExpect } from '@paradoxical-io/common-test';
+
+import { CompactSet } from '../CompactSet';
+
+describe('CompactSet', () => {
+    it('adds values', () => {
+        const set = new CompactSet();
+        set.add(1).add(null).add(undefined);
+        safeExpect(set.values().next().value).toEqual(1);
+        safeExpect(set.keys().next().value).toEqual(1);
+        safeExpect(set.size).toEqual(1);
+    });
+
+    it('does not add null', () => {
+        const set = new CompactSet();
+        set.add(null);
+        safeExpect(set.values().next().done).toEqual(true);
+        safeExpect(set.keys().next().done).toEqual(true);
+        safeExpect(set.size).toEqual(0);
+    });
+
+    it('does not add undefined', () => {
+        const set = new CompactSet();
+        set.add(undefined);
+        safeExpect(set.values().next().done).toEqual(true);
+        safeExpect(set.keys().next().done).toEqual(true);
+        safeExpect(set.size).toEqual(0);
+    });
+
+    it('adds a value via the constructor iterable', () => {
+        const seedSet = new Set([1]);
+        const set = new CompactSet(seedSet);
+        safeExpect(set.values().next().value).toEqual(1);
+        safeExpect(set.keys().next().value).toEqual(1);
+        safeExpect(set.size).toEqual(1);
+    });
+
+    it('adds a value via the constructor array', () => {
+        const set = new CompactSet([1]);
+        safeExpect(set.values().next().value).toEqual(1);
+        safeExpect(set.keys().next().value).toEqual(1);
+        safeExpect(set.size).toEqual(1);
+    });
+
+    it('does not add a null value via the constructor iterable', () => {
+        const seedSet = new Set([1, null, 2]);
+        const set = new CompactSet(seedSet);
+        const iterator = set.values();
+        safeExpect(iterator.next().value).toEqual(1);
+        safeExpect(iterator.next().value).toEqual(2);
+        safeExpect(set.size).toEqual(2);
+    });
+
+    it('does not add an undefined value via the constructor iterable', () => {
+        const seedSet = new Set([1, undefined, 2]);
+        const set = new CompactSet(seedSet);
+        const iterator = set.values();
+        safeExpect(iterator.next().value).toEqual(1);
+        safeExpect(iterator.next().value).toEqual(2);
+        safeExpect(set.size).toEqual(2);
+    });
+
+    it('does not add a null value via the constructor array', () => {
+        const set = new CompactSet([1, null, 2]);
+        const iterator = set.values();
+        safeExpect(iterator.next().value).toEqual(1);
+        safeExpect(iterator.next().value).toEqual(2);
+        safeExpect(set.size).toEqual(2);
+    });
+
+    it('does not add an undefined value via the constructor array', () => {
+        const set = new CompactSet([1, undefined, 2]);
+        const iterator = set.values();
+        safeExpect(iterator.next().value).toEqual(1);
+        safeExpect(iterator.next().value).toEqual(2);
+        safeExpect(set.size).toEqual(2);
+    });
+
+    it('addAll adds many values', () => {
+        const set = new CompactSet();
+        set.addAll([1, 2, null, undefined, 3]);
+        const iterator = set.values();
+        safeExpect(iterator.next().value).toEqual(1);
+        safeExpect(iterator.next().value).toEqual(2);
+        safeExpect(iterator.next().value).toEqual(3);
+        safeExpect(set.size).toEqual(3);
+    });
+
+    it('addAll handles undefined', () => {
+        const set = new CompactSet();
+        set.addAll(undefined);
+        safeExpect(set.size).toEqual(0);
+    });
+
+    it('addAll handles null arrays', () => {
+        const set = new CompactSet();
+        set.addAll(null);
+        safeExpect(set.size).toEqual(0);
+    });
+
+    it('addAll handles empty arrays', () => {
+        const set = new CompactSet();
+        set.addAll([]);
+        safeExpect(set.size).toEqual(0);
+    });
+});

package/src/test/EntityRehydratorTest.ts

@@ -0,0 +1,74 @@
+import { EntityType } from '@coast/core-types/common/EntityType';
+import { ViewTemplateId } from '@coast/core-types/view-template/ViewTemplateId';
+import { WorkflowTemplateId } from '@coast/core-types/workflow-template/WorkflowTemplateId';
+import { CoastLogger } from '@coast/service-common/logger/CoastLogger';
+import { safeExpect } from '@paradoxical-io/common-test';
+
+import { EntityRehydrator } from '../EntityRehydrator';
+
+describe('EntityRehydrator', () => {
+    function mockLogger(): { logger: CoastLogger; warn: jest.Mock } {
+        const warn = jest.fn();
+
+        return { logger: { warn } as unknown as CoastLogger, warn };
+    }
+
+    describe('require', () => {
+        it('returns a stored property that is present', () => {
+            const { logger, warn } = mockLogger();
+            const rehydrator = new EntityRehydrator(EntityType.WORKFLOW_TEMPLATE, logger);
+
+            safeExpect(
+                rehydrator.require({ id: WorkflowTemplateId('wft-1'), parentTemplateId: 'wft-owner' }, 'parentTemplateId')
+            ).toEqual('wft-owner');
+
+            expect(warn).not.toHaveBeenCalled();
+        });
+
+        it('returns the missing property rather than throwing, and warns', () => {
+            const { logger, warn } = mockLogger();
+            const rehydrator = new EntityRehydrator(EntityType.WORKFLOW_TEMPLATE, logger);
+
+            safeExpect(
+                rehydrator.require({ id: WorkflowTemplateId('wft-1'), parentTemplateId: null }, 'parentTemplateId')
+            ).toBeNull();
+
+            expect(warn).toHaveBeenCalledTimes(1);
+
+            expect(warn).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    msg: 'Workflow Template is missing required property parentTemplateId',
+                    event: EntityRehydrator.MISSING_REQUIRED_PROPERTY,
+                    entityType: EntityType.WORKFLOW_TEMPLATE,
+                    id: 'wft-1',
+                    propertyName: 'parentTemplateId',
+                })
+            );
+        });
+
+        it('labels the warning with the entity type it was built for', () => {
+            const { logger, warn } = mockLogger();
+
+            new EntityRehydrator(EntityType.VIEW_TEMPLATE, logger).require(
+                { id: ViewTemplateId('vt-1'), name: undefined },
+                'name'
+            );
+
+            expect(warn).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    msg: 'View Template is missing required property name',
+                    entityType: EntityType.VIEW_TEMPLATE,
+                    id: 'vt-1',
+                })
+            );
+        });
+
+        it('completes without a logger', () => {
+            const rehydrator = new EntityRehydrator(EntityType.WORKFLOW_TEMPLATE);
+
+            safeExpect(
+                rehydrator.require({ id: WorkflowTemplateId('wft-1'), parentTemplateId: undefined }, 'parentTemplateId')
+            ).toBeUndefined();
+        });
+    });
+});

package/src/test/EntityUtilsTest.ts

@@ -0,0 +1,97 @@
+import { EntityType } from '@coast/core-types/common/EntityType';
+import { EntityTypeLabels } from '@coast/core-types/common/EntityTypeLabels';
+import { InvalidEntityReferenceException } from '@coast/core-types/exception/InvalidEntityReferenceException';
+import { NotFoundException } from '@coast/core-types/exception/NotFoundException';
+import { assertType } from '@coast/service-common/types/assertType';
+import { Equals } from '@coast/service-common/types/Equals';
+import { safeExpect } from '@paradoxical-io/common-test';
+
+import { EntityUtils } from '../EntityUtils';
+
+describe('EntityUtils', () => {
+    describe('assertValidEntityReference', () => {
+        it('should throw if value is not defined', () => {
+            const x = undefined as object | undefined;
+            try {
+                EntityUtils.assertValidEntityReference(x, EntityType.WORKFLOW_ENTITY);
+            } catch (error) {
+                expect(error).toBeInstanceOf(InvalidEntityReferenceException);
+
+                safeExpect((error as InvalidEntityReferenceException).message).toEqual(
+                    `Invalid entity reference: ${EntityTypeLabels[EntityType.WORKFLOW_ENTITY]} not found`
+                );
+
+                safeExpect((error as InvalidEntityReferenceException).additionalData).toMatchObject({
+                    entityType: EntityType.WORKFLOW_ENTITY,
+                });
+            }
+        });
+
+        it('should use custom error message', () => {
+            const x = undefined as object | undefined;
+            try {
+                EntityUtils.assertValidEntityReference(x, EntityType.WORKFLOW_ENTITY, {
+                    message: 'x should exist...',
+                    id: 'abc-123',
+                });
+            } catch (error) {
+                expect(error).toBeInstanceOf(InvalidEntityReferenceException);
+                safeExpect((error as InvalidEntityReferenceException).message).toEqual('x should exist...');
+
+                safeExpect((error as InvalidEntityReferenceException).additionalData).toMatchObject({
+                    entityType: EntityType.WORKFLOW_ENTITY,
+                    id: 'abc-123',
+                });
+            }
+        });
+
+        it('should not throw and should type narrow if value is defined', () => {
+            const x = { id: 'abc' } as object | undefined;
+            assertType<Equals<typeof x, object | undefined>>();
+
+            EntityUtils.assertValidEntityReference(x, EntityType.COMPONENT);
+            assertType<Equals<typeof x, object>>();
+        });
+    });
+
+    describe('assertEntityFound', () => {
+        it('should throw if value is not defined', () => {
+            const x = undefined as object | undefined;
+            try {
+                EntityUtils.assertEntityFound(x, EntityType.WORKFLOW_ENTITY);
+            } catch (error) {
+                expect(error).toBeInstanceOf(NotFoundException);
+
+                safeExpect((error as NotFoundException).additionalData).toMatchObject({
+                    entityType: EntityType.WORKFLOW_ENTITY,
+                });
+            }
+        });
+
+        it('should use custom error message', () => {
+            const x = undefined as object | undefined;
+            try {
+                EntityUtils.assertEntityFound(x, EntityType.WORKFLOW_ENTITY, {
+                    message: 'x should exist...',
+                    id: 'abc-123',
+                });
+            } catch (error) {
+                expect(error).toBeInstanceOf(NotFoundException);
+                safeExpect((error as NotFoundException).message).toEqual('x should exist...');
+
+                safeExpect((error as NotFoundException).additionalData).toMatchObject({
+                    entityType: EntityType.WORKFLOW_ENTITY,
+                    id: 'abc-123',
+                });
+            }
+        });
+
+        it('should not throw and should type narrow if value is defined', () => {
+            const x = { id: 'abc' } as object | undefined;
+            assertType<Equals<typeof x, object | undefined>>();
+
+            EntityUtils.assertEntityFound(x, EntityType.COMPONENT);
+            assertType<Equals<typeof x, object>>();
+        });
+    });
+});