@coast/core-utils 0.0.25 → 0.0.28

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