@outputai/core 0.8.2-next.42a0ddf.0 → 0.8.2-next.57bc8d6.0

package/src/helpers/object.spec.js

@@ -0,0 +1,377 @@
+import { describe, it, expect, vi } from 'vitest';
+import { assignImmutableProperty, clone, deepMerge, deepMergeWithResolver, isPlainObject, shuffleArray } from './object.js';
+
+describe( 'clone', () => {
+  it( 'produces a deep copy without shared references', () => {
+    const original = { a: 1, nested: { b: 2 } };
+    const copied = clone( original );
+
+    copied.nested.b = 3;
+
+    expect( original.nested.b ).toBe( 2 );
+    expect( copied.nested.b ).toBe( 3 );
+    expect( copied ).not.toBe( original );
+  } );
+
+  it( 'deep copies JSON-compatible arrays and objects', () => {
+    const original = {
+      arr: [ 1, { nested: true } ],
+      str: 'value',
+      bool: false,
+      nil: null
+    };
+    const copied = clone( original );
+
+    copied.arr[1].nested = false;
+
+    expect( copied ).toEqual( {
+      arr: [ 1, { nested: false } ],
+      str: 'value',
+      bool: false,
+      nil: null
+    } );
+    expect( original.arr[1].nested ).toBe( true );
+    expect( copied ).not.toBe( original );
+    expect( copied.arr ).not.toBe( original.arr );
+  } );
+
+  it( 'returns primitive JSON values when they can be parsed', () => {
+    expect( clone( null ) ).toBeNull();
+    expect( clone( true ) ).toBe( true );
+    expect( clone( false ) ).toBe( false );
+    expect( clone( 123 ) ).toBe( 123 );
+    expect( clone( 'hello' ) ).toBe( 'hello' );
+  } );
+
+  it( 'returns original values when JSON serialization produces no parseable payload', () => {
+    const sym = Symbol( 'x' );
+    const fn = () => {};
+    class Foo {}
+
+    expect( clone( undefined ) ).toBeUndefined();
+    expect( clone( sym ) ).toBe( sym );
+    expect( clone( fn ) ).toBe( fn );
+    expect( clone( Foo ) ).toBe( Foo );
+    expect( clone( Date ) ).toBe( Date );
+    expect( clone( Object ) ).toBe( Object );
+    expect( clone( Number ) ).toBe( Number );
+  } );
+
+  it( 'returns original values when JSON serialization throws', () => {
+    const circular = { name: 'circular' };
+    circular.self = circular;
+    const bigint = 1n;
+
+    expect( clone( circular ) ).toBe( circular );
+    expect( clone( bigint ) ).toBe( bigint );
+  } );
+
+  it( 'keeps JSON.stringify semantics for special numeric values', () => {
+    expect( clone( NaN ) ).toBeNull();
+    expect( clone( Infinity ) ).toBeNull();
+    expect( clone( -Infinity ) ).toBeNull();
+  } );
+
+  it( 'keeps JSON.stringify semantics for non-plain object instances', () => {
+    const date = new Date( '2025-01-01T00:00:00.000Z' );
+
+    expect( clone( date ) ).toBe( '2025-01-01T00:00:00.000Z' );
+    expect( clone( /abc/ ) ).toEqual( {} );
+    expect( clone( new Map( [ [ 'a', 1 ] ] ) ) ).toEqual( {} );
+    expect( clone( new Set( [ 1, 2 ] ) ) ).toEqual( {} );
+  } );
+
+  it( 'drops object properties that JSON.stringify omits', () => {
+    const sym = Symbol( 'x' );
+    const original = {
+      kept: 'yes',
+      missing: undefined,
+      fn: () => {},
+      sym
+    };
+
+    expect( clone( original ) ).toEqual( { kept: 'yes' } );
+  } );
+} );
+
+describe( 'deepMerge', () => {
+  it( 'Overwrites properties in object "a"', () => {
+    const a = {
+      a: 1,
+      b: {
+        c: 2
+      }
+    };
+    const b = {
+      a: false,
+      b: {
+        c: true
+      }
+    };
+    expect( deepMerge( a, b ) ).toEqual( {
+      a: false,
+      b: {
+        c: true
+      }
+    } );
+  } );
+
+  it( 'Adds properties existing in "b" but absent in "a"', () => {
+    const a = {
+      a: 1
+    };
+    const b = {
+      a: false,
+      b: true
+    };
+    expect( deepMerge( a, b ) ).toEqual( {
+      a: false,
+      b: true
+    } );
+  } );
+
+  it( 'Keep extra properties in "a"', () => {
+    const a = {
+      a: 1
+    };
+    const b = {
+      b: true
+    };
+    expect( deepMerge( a, b ) ).toEqual( {
+      a: 1,
+      b: true
+    } );
+  } );
+
+  it( 'Merge object is a clone', () => {
+    const a = {
+      a: 1
+    };
+    const b = {
+      b: 1
+    };
+    const result = deepMerge( a, b );
+    a.a = 2;
+    b.b = 2;
+    expect( result.a ).toEqual( 1 );
+  } );
+
+  it( 'Returns copy of "a" if "b" is not an object', () => {
+    const a = {
+      a: 1
+    };
+    expect( deepMerge( a, null ) ).toEqual( { a: 1 } );
+    expect( deepMerge( a, undefined ) ).toEqual( { a: 1 } );
+  } );
+
+  it( 'Copy of object "a" is a clone', () => {
+    const a = {
+      a: 1
+    };
+    const result = deepMerge( a, null );
+    a.a = 2;
+    expect( result.a ).toEqual( 1 );
+  } );
+
+  it( 'Throws when first argument is not a plain object', () => {
+    expect( () => deepMerge( Function ) ).toThrow( Error );
+    expect( () => deepMerge( () => {} ) ).toThrow( Error );
+    expect( () => deepMerge( 'a' ) ).toThrow( Error );
+    expect( () => deepMerge( true ) ).toThrow( Error );
+    expect( () => deepMerge( /a/ ) ).toThrow( Error );
+    expect( () => deepMerge( [] ) ).toThrow( Error );
+    expect( () => deepMerge( class Foo {}, class Foo {} ) ).toThrow( Error );
+    expect( () => deepMerge( Number.constructor, Number.constructor ) ).toThrow( Error );
+    expect( () => deepMerge( Number.constructor.prototype, Number.constructor.prototype ) ).toThrow( Error );
+  } );
+} );
+
+describe( 'deepMergeWithResolver', () => {
+  it( 'uses resolver for existing leaf values, including nested leaves', () => {
+    const a = {
+      cost: { total: 1 },
+      tokens: { total: 2, input: 3 }
+    };
+    const b = {
+      cost: { total: 4 },
+      tokens: { total: 5, input: 6, output: 7 }
+    };
+
+    expect( deepMergeWithResolver( a, b, ( x, y ) => x + y ) ).toEqual( {
+      cost: { total: 5 },
+      tokens: { total: 7, input: 9, output: 7 }
+    } );
+  } );
+
+  it( 'copies values from "b" when they do not exist in "a"', () => {
+    const resolver = vi.fn( ( x, y ) => x + y );
+
+    expect( deepMergeWithResolver( { a: 1 }, { b: 2, nested: { c: 3 } }, resolver ) ).toEqual( {
+      a: 1,
+      b: 2,
+      nested: { c: 3 }
+    } );
+    expect( resolver ).not.toHaveBeenCalled();
+  } );
+
+  it( 'keeps extra values from "a" when absent from "b"', () => {
+    expect( deepMergeWithResolver( { a: 1, nested: { kept: 2 } }, { b: 3 }, ( x, y ) => x + y ) ).toEqual( {
+      a: 1,
+      nested: { kept: 2 },
+      b: 3
+    } );
+  } );
+
+  it( 'returns a clone of "a" when "b" is not an object', () => {
+    const a = { nested: { value: 1 } };
+    const result = deepMergeWithResolver( a, null, ( x, y ) => x + y );
+
+    a.nested.value = 2;
+    expect( result ).toEqual( { nested: { value: 1 } } );
+  } );
+
+  it( 'throws when first argument is not a plain object', () => {
+    expect( () => deepMergeWithResolver( null, {}, ( x, y ) => x + y ) ).toThrow( Error );
+    expect( () => deepMergeWithResolver( [], {}, ( x, y ) => x + y ) ).toThrow( Error );
+    expect( () => deepMergeWithResolver( 'a', {}, ( x, y ) => x + y ) ).toThrow( Error );
+  } );
+} );
+
+describe( 'isPlainObject', () => {
+  it( 'Detects plain objects', () => {
+    expect( isPlainObject( {} ) ).toBe( true );
+    expect( isPlainObject( { a: 1 } ) ).toBe( true );
+    expect( isPlainObject( new Object() ) ).toBe( true );
+    expect( isPlainObject( new Object( { foo: 'bar' } ) ) ).toBe( true );
+    expect( isPlainObject( Object.create( {}.constructor.prototype ) ) ).toBe( true );
+    expect( isPlainObject( Object.create( Object.prototype ) ) ).toBe( true );
+  } );
+
+  it( 'Detects plain objects with different prototypes than Object.prototype', () => {
+    // Object with null prototype
+    expect( isPlainObject( Object.create( null ) ) ).toBe( true );
+  } );
+
+  it( 'Detects non plain objects that had their __proto__ mutated to Object.prototype or null', () => {
+    class Foo {}
+    const x = new Foo();
+    x.__proto__ = Object.prototype;
+    expect( isPlainObject( x ) ).toBe( true );
+
+    const y = new Foo();
+    y.__proto__ = null;
+    expect( isPlainObject( y ) ).toBe( true );
+  } );
+
+  it( 'Returns false for object which the prototype is not Object.prototype or null', () => {
+    // Object which the prototype is a plain {}
+    expect( isPlainObject( Object.create( {} ) ) ).toBe( false );
+    // Object which prototype is a another object with null prototype
+    expect( isPlainObject( Object.create( Object.create( null ) ) ) ).toBe( false );
+  } );
+
+  it( 'Returns false for functions', () => {
+    expect( isPlainObject( Function ) ).toBe( false );
+    expect( isPlainObject( () => {} ) ).toBe( false );
+    expect( isPlainObject( class Foo {} ) ).toBe( false );
+    expect( isPlainObject( Number.constructor ) ).toBe( false );
+    expect( isPlainObject( Number.constructor.prototype ) ).toBe( false );
+  } );
+
+  it( 'Returns false for arrays', () => {
+    expect( isPlainObject( [ 1, 2, 3 ] ) ).toBe( false );
+    expect( isPlainObject( [] ) ).toBe( false );
+    expect( isPlainObject( Array( 3 ) ) ).toBe( false );
+  } );
+
+  it( 'Returns false for primitives', () => {
+    expect( isPlainObject( null ) ).toBe( false );
+    expect( isPlainObject( undefined ) ).toBe( false );
+    expect( isPlainObject( false ) ).toBe( false );
+    expect( isPlainObject( true ) ).toBe( false );
+    expect( isPlainObject( 1 ) ).toBe( false );
+    expect( isPlainObject( 0 ) ).toBe( false );
+    expect( isPlainObject( '' ) ).toBe( false );
+    expect( isPlainObject( 'foo' ) ).toBe( false );
+    expect( isPlainObject( Symbol( 'foo' ) ) ).toBe( false );
+    expect( isPlainObject( Symbol.for( 'foo' ) ) ).toBe( false );
+  } );
+
+  it( 'Returns true for built in objects', () => {
+    expect( isPlainObject( Math ) ).toBe( true );
+    expect( isPlainObject( JSON ) ).toBe( true );
+  } );
+
+  it( 'Returns false for built in types', () => {
+    expect( isPlainObject( String ) ).toBe( false );
+    expect( isPlainObject( Number ) ).toBe( false );
+    expect( isPlainObject( Date ) ).toBe( false );
+  } );
+
+  it( 'Returns false for other instance where prototype is not object or null', () => {
+    expect( isPlainObject( /foo/ ) ).toBe( false );
+    expect( isPlainObject( new RegExp( 'foo' ) ) ).toBe( false );
+    expect( isPlainObject( new Date() ) ).toBe( false );
+    class Foo {}
+    expect( isPlainObject( new Foo() ) ).toBe( false );
+    expect( isPlainObject( Object.create( ( class Foo {} ).prototype ) ) ).toBe( false );
+  } );
+
+  it( 'Returns false if tries to change the prototype to simulate an object', () => {
+    function Bar() {}
+    Bar.prototype = Object.create( null );
+    expect( isPlainObject( new Bar() ) ).toBe( false );
+  } );
+
+  it( 'Returns false if object proto was mutated to anything else than object or null', () => {
+    const zum = {};
+    zum.__proto__ = Number.prototype;
+    expect( isPlainObject( zum ) ).toBe( false );
+  } );
+} );
+
+describe( 'assignImmutableProperty', () => {
+  it( 'defines a non-writable, non-configurable, non-enumerable property', () => {
+    const obj = {};
+    const key = Symbol( 'metadata' );
+    const value = { name: 'test' };
+
+    expect( assignImmutableProperty( obj, key, value ) ).toBe( obj );
+    expect( obj[key] ).toBe( value );
+    expect( Object.getOwnPropertyDescriptor( obj, key ) ).toEqual( {
+      value,
+      writable: false,
+      configurable: false,
+      enumerable: false
+    } );
+    expect( Object.keys( obj ) ).toEqual( [] );
+  } );
+
+  it( 'prevents reassignment and redefinition', () => {
+    const obj = {};
+    const key = 'metadata';
+
+    assignImmutableProperty( obj, key, 'original' );
+
+    expect( () => {
+      obj[key] = 'updated';
+    } ).toThrow( TypeError );
+    expect( () => {
+      Object.defineProperty( obj, key, { value: 'updated' } );
+    } ).toThrow( TypeError );
+    expect( obj[key] ).toBe( 'original' );
+  } );
+} );
+
+describe( 'shuffleArray', () => {
+  it( 'returns a shuffled copy based on random sort keys', () => {
+    vi.spyOn( Math, 'random' )
+      .mockReturnValueOnce( 0.4 )
+      .mockReturnValueOnce( 0.1 )
+      .mockReturnValueOnce( 0.3 );
+    const arr = [ 'a', 'b', 'c' ];
+
+    expect( shuffleArray( arr ) ).toEqual( [ 'b', 'c', 'a' ] );
+    expect( arr ).toEqual( [ 'a', 'b', 'c' ] );
+  } );
+} );

package/src/helpers/promise.js

@@ -0,0 +1,29 @@
+/**
+ * Builds a promise that can be resolved from the outside.
+ */
+export class CancellablePromise {
+  #promise = null;
+  #complete = null;
+  #completed = false;
+
+  constructor() {
+    this.#promise = new Promise( resolve => {
+      this.#complete = () => {
+        resolve();
+        this.#completed = true;
+      };
+    } );
+  }
+  /** Retrieves the promise */
+  get promise() {
+    return this.#promise;
+  }
+  /** Returns whether the promise is resolved or not */
+  get completed() {
+    return this.#completed;
+  }
+  /** Resolves the promise */
+  complete() {
+    this.#complete();
+  }
+};

package/src/helpers/promise.spec.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CancellablePromise } from './promise.js';
+
+describe( 'CancellablePromise', () => {
+  it( 'exposes a pending promise until it is completed', async () => {
+    const cancellable = new CancellablePromise();
+    const onComplete = vi.fn();
+
+    cancellable.promise.then( onComplete );
+    await Promise.resolve();
+
+    expect( cancellable.completed ).toBe( false );
+    expect( onComplete ).not.toHaveBeenCalled();
+
+    cancellable.complete();
+    await cancellable.promise;
+
+    expect( cancellable.completed ).toBe( true );
+    expect( onComplete ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'can be completed multiple times without resolving again', async () => {
+    const cancellable = new CancellablePromise();
+    const onComplete = vi.fn();
+
+    cancellable.promise.then( onComplete );
+    cancellable.complete();
+    cancellable.complete();
+    await cancellable.promise;
+    await Promise.resolve();
+
+    expect( cancellable.completed ).toBe( true );
+    expect( onComplete ).toHaveBeenCalledOnce();
+  } );
+} );

package/src/helpers/string.js

@@ -0,0 +1,30 @@
+/**
+ * Returns true if string value is stringbool and true
+ * @param {string} v
+ * @returns
+ */
+export const isStringboolTrue = v => [ '1', 'true', 'on' ].includes( v );
+
+/**
+ * Shortens a UUID by re-encoding it to base62.
+ *
+ * This is a Temporal friendly, without crypto or Buffer.
+ * @param {string} uuid
+ * @returns {string}
+ */
+export const toUrlSafeBase64 = uuid => {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-';
+  const alphabetLen = alphabet.length;
+  const base = BigInt( alphabetLen );
+  const hex = uuid.replace( /-/g, '' );
+
+  const toDigits = n => n <= 0n ? [] : toDigits( n / base ).concat( alphabet[Number( n % base )] );
+  return toDigits( BigInt( '0x' + hex ) ).join( '' );
+};
+
+/**
+ * Escape regexp characters in a string
+ * @param {*} value
+ * @returns
+ */
+export const rxEscape = v => v.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' );

package/src/helpers/string.spec.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { toUrlSafeBase64, rxEscape } from './string.js';
+
+describe( 'toUrlSafeBase64', () => {
+  const urlSafeAlphabet = /^[A-Za-z0-9_-]+$/;
+
+  it( 'returns a string for a valid UUID', () => {
+    const uuid = '550e8400-e29b-41d4-a716-446655440000';
+    expect( typeof toUrlSafeBase64( uuid ) ).toBe( 'string' );
+    expect( toUrlSafeBase64( uuid ).length ).toBeGreaterThan( 0 );
+  } );
+
+  it( 'output length is 21 or 22 for a standard UUID', () => {
+    const uuid = '550e8400-e29b-41d4-a716-446655440000';
+    const out = toUrlSafeBase64( uuid );
+    expect( out.length ).toBeGreaterThanOrEqual( 21 );
+    expect( out.length ).toBeLessThanOrEqual( 22 );
+  } );
+
+  it( 'output contains only url-safe alphabet characters', () => {
+    const uuid = '550e8400-e29b-41d4-a716-446655440000';
+    const out = toUrlSafeBase64( uuid );
+    expect( out ).toMatch( urlSafeAlphabet );
+  } );
+
+  it( 'is deterministic for the same UUID', () => {
+    const uuid = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+    expect( toUrlSafeBase64( uuid ) ).toBe( toUrlSafeBase64( uuid ) );
+  } );
+
+  it( 'different UUIDs produce different strings', () => {
+    const a = toUrlSafeBase64( '550e8400-e29b-41d4-a716-446655440000' );
+    const b = toUrlSafeBase64( '6ba7b810-9dad-11d1-80b4-00c04fd430c8' );
+    expect( a ).not.toBe( b );
+  } );
+
+  it( 'strips hyphens and encodes hex (same as 32-char hex)', () => {
+    const withHyphens = '550e8400-e29b-41d4-a716-446655440000';
+    const hexOnly = '550e8400e29b41d4a716446655440000';
+    expect( toUrlSafeBase64( withHyphens ) ).toBe( toUrlSafeBase64( hexOnly ) );
+  } );
+} );
+
+describe( 'rxEscape', () => {
+  it( 'escapes all regexp metacharacters', () => {
+    expect( rxEscape( '.*+?^${}()|[]\\' ) ).toBe( '\\.\\*\\+\\?\\^\\$\\{\\}\\(\\)\\|\\[\\]\\\\' );
+  } );
+
+  it( 'keeps file URL paths matchable as literal regexp input', () => {
+    const path = 'file://foo/bar';
+    const rx = new RegExp( `^${rxEscape( path )}$` );
+
+    expect( rx.test( path ) ).toBe( true );
+    expect( rx.test( 'file://foo/bar/baz' ) ).toBe( false );
+  } );
+
+  it( 'keeps Windows paths matchable as literal regexp input', () => {
+    const path = String.raw`C:\foo\bar`;
+    const rx = new RegExp( `^${rxEscape( path )}$` );
+
+    expect( rx.test( path ) ).toBe( true );
+    expect( rx.test( String.raw`C:\foo\bar\baz` ) ).toBe( false );
+  } );
+} );