vest-utils 1.4.0 → 1.5.0

package/src/SimpleStateMachine.ts

@@ -1,157 +0,0 @@
-import { isFailure, makeResult, Result } from './Result';
-import { CB } from './utilityTypes';
-
-const STATE_WILD_CARD = '*';
-type TStateWildCard = typeof STATE_WILD_CARD;
-
-type TransitionTarget<S extends string> = S | [S, CB<boolean, [payload?: any]>];
-type StatesMap<S extends string = string, A extends string = string> = Record<
-  S | TStateWildCard,
-  Partial<Record<A, TransitionTarget<S>>>
->;
-
-export type TStateMachine<
-  S extends string = string,
-  A extends string = string,
-> = {
-  initial: S;
-  states: Partial<StatesMap<S, A>>;
-};
-
-export type TStateMachineApi<
-  S extends string = string,
-  A extends string = string,
-> = {
-  getState: CB<S>;
-  initial: CB<S>;
-  staticTransition: (from: S, action: A, payload?: any) => S;
-  transition: (action: A, payload?: any) => Result<void, string>;
-};
-
-type TransitionValue<V> = V extends [infer T, any]
-  ? T extends string
-    ? T
-    : never
-  : V extends string
-    ? V
-    : never;
-
-type Values<T> = T[keyof T];
-
-type StateConfigs<M extends { states: Record<string, any> }> = Values<
-  M['states']
->;
-
-type ActionFromConfig<M extends { states: Record<string, any> }> =
-  StateConfigs<M> extends infer SC
-    ? SC extends any
-      ? Extract<keyof SC, string>
-      : never
-    : never;
-
-type TargetStatesFromConfig<M extends { states: Record<string, any> }> =
-  StateConfigs<M> extends infer SC
-    ? SC extends any
-      ? TransitionValue<Values<SC>>
-      : never
-    : never;
-
-type StateFromConfig<
-  M extends { initial: string; states: Record<string, any> },
-> =
-  | M['initial']
-  | Extract<keyof M['states'], string>
-  | TargetStatesFromConfig<M>;
-
-export function StateMachine<
-  M extends { initial: string; states: Record<string, any> },
->(machine: M): TStateMachineApi<StateFromConfig<M>, ActionFromConfig<M>> {
-  type SMState = StateFromConfig<M>;
-  type SMAction = ActionFromConfig<M>;
-
-  const typedMachine = machine as TStateMachine<SMState, SMAction>;
-
-  let state = typedMachine.initial;
-
-  const api = { getState, initial, staticTransition, transition };
-
-  return api;
-
-  function getState(): SMState {
-    return state;
-  }
-
-  function initial(): SMState {
-    return machine.initial;
-  }
-
-  function transition(action: SMAction, payload?: any): Result<void, string> {
-    const result = calculateNextState(typedMachine, state, action, payload);
-
-    if (isFailure(result)) {
-      return makeResult.Err(result.error);
-    }
-
-    state = result.value;
-    return makeResult.Ok(undefined);
-  }
-
-  function staticTransition(
-    from: SMState,
-    action: SMAction,
-    payload?: any,
-  ): SMState {
-    const transitionTo = getTransitionTarget(typedMachine, from, action);
-    const target = Array.isArray(transitionTo)
-      ? evaluateConditionalTarget(transitionTo, from, payload)
-      : transitionTo;
-
-    return !target || target === from ? from : (target as SMState);
-  }
-}
-
-function getTransitionTarget<S extends string, A extends string>(
-  machine: TStateMachine<S, A>,
-  from: S,
-  action: A,
-): TransitionTarget<S> | undefined {
-  return (
-    machine.states[from]?.[action] ?? machine.states[STATE_WILD_CARD]?.[action]
-  );
-}
-
-function evaluateConditionalTarget<S extends string>(
-  target: [S, CB<boolean, [payload?: any]>],
-  from: S,
-  payload?: any,
-): S {
-  const [nextState, conditional] = target;
-  return conditional(payload) ? nextState : from;
-}
-
-function calculateNextState<S extends string, A extends string>(
-  machine: TStateMachine<S, A>,
-  from: S,
-  action: A,
-  payload?: any,
-): Result<S, string> {
-  const transitionTo = getTransitionTarget(machine, from, action);
-
-  if (!transitionTo) {
-    return makeResult.Err(
-      `Invalid transition: "${action}" from state "${from}"`,
-    );
-  }
-
-  if (Array.isArray(transitionTo)) {
-    const [candidateState, conditional] = transitionTo;
-    if (!conditional(payload)) {
-      return makeResult.Err(
-        `Invalid transition: "${action}" from state "${from}" (conditional failed)`,
-      );
-    }
-    return makeResult.Ok(candidateState);
-  }
-
-  return makeResult.Ok(transitionTo as S);
-}

package/src/StringObject.ts

@@ -1,6 +0,0 @@
-import dynamicValue from './dynamicValue';
-import type { Stringable } from './utilityTypes';
-
-export function StringObject(value?: Stringable): String {
-  return new String(dynamicValue(value));
-}

package/src/__tests__/Architecture.test.ts

@@ -1,69 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-
-import { Brand, makeBrand } from '../Brand';
-import { IO } from '../IO';
-import { makeResult, isResult, isSuccess, isFailure } from '../Result';
-
-// --- CONTRACT: Branded Types ---
-describe('Architecture: Branded Types', () => {
-  type UserId = Brand<string, 'UserId'>;
-  type PostId = Brand<string, 'PostId'>;
-
-  it('should not allow assignment of raw string to Branded type (Static Check)', () => {
-    const raw = 'user_123';
-    const userId = makeBrand<UserId>(raw);
-    // @ts-expect-error PostId is not assignable to UserId
-    const _postId: PostId = userId;
-
-    expect(userId).toBe(raw);
-  });
-});
-
-// --- CONTRACT: Result/Error Handling ---
-describe('Architecture: Result Monad', () => {
-  it('should encapsulate errors as values', () => {
-    const errorResult = makeResult.Err('Something went wrong');
-    expect(isFailure(errorResult)).toBe(true);
-    expect(errorResult.error).toBe('Something went wrong');
-  });
-
-  it('should encapsulate success values', () => {
-    const successResult = makeResult.Ok(42);
-    expect(isSuccess(successResult)).toBe(true);
-    expect(successResult.value).toBe(42);
-  });
-
-  it('should support mapping without throwing', () => {
-    const val = makeResult.Ok(10);
-    const newResult = val.map(x => x * 2);
-
-    expect(isSuccess(newResult)).toBe(true);
-    // @ts-ignore
-    expect(newResult.value).toBe(20);
-  });
-
-  it('should identify generic result shapes', () => {
-    const okShape = makeResult.Ok('ok');
-    const errShape = makeResult.Err('err');
-    expect(isResult(okShape)).toBe(true);
-    expect(isResult(errShape)).toBe(true);
-    expect(isResult({})).toBe(false);
-  });
-});
-
-// --- CONTRACT: Explicit Side Effects (IO) ---
-describe('Architecture: IO / Effect', () => {
-  it('should not execute side effect immediately', () => {
-    const spy = vi.fn();
-
-    const sideEffectFn = (): IO<void> => {
-      return () => spy();
-    };
-
-    const effect = sideEffectFn();
-    expect(spy).not.toHaveBeenCalled();
-
-    effect();
-    expect(spy).toHaveBeenCalled();
-  });
-});

package/src/__tests__/Predicates.test.ts

@@ -1,118 +0,0 @@
-import { all, any } from '../Predicates';
-import { describe, it, vi, expect } from 'vitest';
-
-describe('Predicates', () => {
-  describe('all', () => {
-    it('Should return a predicate function', () => {
-      expect(typeof all()).toBe('function');
-    });
-
-    it('Should return true if all predicates return true', () => {
-      const predicate = all(
-        value => value > 0,
-        value => value < 10,
-      );
-
-      expect(predicate(5)).toBe(true);
-    });
-
-    it('Should return false if any predicate returns false', () => {
-      const predicate = all(
-        value => value > 0,
-        value => value < 10,
-      );
-
-      expect(predicate(15)).toBe(false);
-    });
-
-    it('Should return false if no predicates are passed', () => {
-      const predicate = all();
-
-      expect(predicate(15)).toBe(false);
-    });
-
-    it('Should return false if predicates are not functions', () => {
-      const predicate = all(
-        value => value > 0,
-        value => value < 10,
-        // @ts-ignore - Testing invalid input
-        'not a function',
-      );
-
-      expect(predicate(15)).toBe(false);
-    });
-
-    it('Should pass each predicate the value', () => {
-      const spy1 = vi.fn(value => value > 0);
-      const spy2 = vi.fn(value => value < 10);
-
-      const predicate = all(spy1, spy2);
-
-      predicate(5);
-
-      expect(spy1).toHaveBeenCalledWith(5);
-      expect(spy2).toHaveBeenCalledWith(5);
-    });
-
-    it('When passing explicit true as a predicate, should return true', () => {
-      expect(all(true, true, true)(5)).toBe(true);
-    });
-
-    it('When passing explicit false as a predicate, should return false', () => {
-      expect(all(true, false, false)(5)).toBe(false);
-    });
-  });
-
-  describe('any', () => {
-    it('Shold return a predicate function', () => {
-      expect(typeof any()).toBe('function');
-    });
-
-    it('Should return true if any predicate returns true', () => {
-      expect(
-        any(
-          value => value > 0,
-          value => value === 10,
-        )(5),
-      ).toBe(true);
-      expect(
-        any(
-          value => value === 10,
-          value => value > 0,
-        )(5),
-      ).toBe(true);
-    });
-
-    it('Should return true if all predicates return true', () => {
-      const predicate = any(
-        value => value > 0,
-        value => value === 10,
-      );
-
-      expect(predicate(10)).toBe(true);
-    });
-
-    it('Should return false if all predicates return false', () => {
-      const predicate = any(
-        value => value > 0,
-        value => value === 10,
-      );
-
-      expect(predicate(-5)).toBe(false);
-    });
-
-    it('Should return false if no predicates are passed', () => {
-      const predicate = any();
-
-      expect(predicate(15)).toBe(false);
-    });
-
-    it('When passing explicit true as a predicate, should return true', () => {
-      expect(any(true, false, false)(5)).toBe(true);
-    });
-
-    it('When passing explicit false as a predicate, should return false', () => {
-      expect(any(false, false, false)(5)).toBe(false);
-    });
-  });
-});

package/src/__tests__/Result.test.ts

@@ -1,284 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-
-import { isFailure, isResult, isSuccess, makeResult, unwrap } from '../Result';
-
-describe('Result', () => {
-  describe('makeResult', () => {
-    describe('Ok', () => {
-      it('should return a Success result', () => {
-        const result = makeResult.Ok(1);
-        expect(result.type).toBe('ok');
-        expect(result.value).toBe(1);
-      });
-
-      it('should have correct methods', () => {
-        const result = makeResult.Ok(1);
-        expect(typeof result.map).toBe('function');
-        expect(typeof result.chain).toBe('function');
-        expect(typeof result.mapError).toBe('function');
-        expect(typeof result.match).toBe('function');
-      });
-    });
-
-    describe('Err', () => {
-      it('should return a Failure result', () => {
-        const result = makeResult.Err('error');
-        expect(result.type).toBe('err');
-        expect(result.error).toBe('error');
-      });
-
-      it('should have correct methods', () => {
-        const result = makeResult.Err('error');
-        expect(typeof result.map).toBe('function');
-        expect(typeof result.chain).toBe('function');
-        expect(typeof result.mapError).toBe('function');
-        expect(typeof result.match).toBe('function');
-      });
-    });
-  });
-
-  describe('isResult', () => {
-    it('should return true for Success result', () => {
-      expect(isResult(makeResult.Ok(1))).toBe(true);
-    });
-
-    it('should return true for Failure result', () => {
-      expect(isResult(makeResult.Err('error'))).toBe(true);
-    });
-
-    it('should return false for non-result objects', () => {
-      expect(isResult({})).toBe(false);
-      expect(isResult(null)).toBe(false);
-      expect(isResult(undefined)).toBe(false);
-      expect(isResult(1)).toBe(false);
-      expect(isResult('string')).toBe(false);
-      expect(isResult({ type: 'ok' })).toBe(false); // Missing value
-      expect(isResult({ type: 'err' })).toBe(false); // Missing error
-      expect(isResult({ value: 1 })).toBe(false); // Missing type
-    });
-  });
-
-  describe('isSuccess', () => {
-    it('should return true for Success result', () => {
-      expect(isSuccess(makeResult.Ok(1))).toBe(true);
-    });
-
-    it('should return false for Failure result', () => {
-      expect(isSuccess(makeResult.Err('error'))).toBe(false);
-    });
-  });
-
-  describe('isFailure', () => {
-    it('should return true for Failure result', () => {
-      expect(isFailure(makeResult.Err('error'))).toBe(true);
-    });
-
-    it('should return false for Success result', () => {
-      expect(isFailure(makeResult.Ok(1))).toBe(false);
-    });
-  });
-
-  describe('unwrap', () => {
-    it('should return value if result is Success', () => {
-      const result = makeResult.Ok(100);
-      expect(unwrap(result)).toBe(100);
-      expect(result.unwrap()).toBe(100);
-    });
-
-    it('should throw error if result is Failure', () => {
-      const error = new Error('fail');
-      const result = makeResult.Err(error);
-      expect(() => unwrap(result)).toThrow(error);
-      expect(() => result.unwrap()).toThrow(error);
-    });
-
-    it('should throw Error object if failure contains non-Error', () => {
-      const result = makeResult.Err('string error');
-      expect(() => unwrap(result)).toThrow('string error');
-      expect(() => result.unwrap()).toThrow('string error');
-      try {
-        result.unwrap();
-      } catch (e) {
-        expect(e).toBeInstanceOf(Error);
-        expect((e as Error).message).toBe('string error');
-      }
-    });
-  });
-
-  describe('unwrapOr', () => {
-    it('should return value if result is Success', () => {
-      const result = makeResult.Ok(100);
-      expect(result.unwrapOr(200)).toBe(100);
-    });
-
-    it('should return default value if result is Failure', () => {
-      const result = makeResult.Err<number>('error');
-      expect(result.unwrapOr(200)).toBe(200);
-    });
-  });
-
-  describe('Success methods', () => {
-    describe('map', () => {
-      it('should transform the value', () => {
-        const result = makeResult.Ok(1).map(x => x + 1);
-        expect(unwrap(result)).toBe(2);
-      });
-    });
-
-    describe('chain', () => {
-      it('should chain with another Result', () => {
-        const result = makeResult.Ok(1).chain(x => makeResult.Ok(x + 1));
-        expect(unwrap(result)).toBe(2);
-      });
-
-      it('should chain with a Failure', () => {
-        const result = makeResult.Ok(1).chain(() => makeResult.Err('fail'));
-        expect(isFailure(result)).toBe(true);
-        expect((result as any).error).toBe('fail');
-      });
-    });
-
-    describe('mapError', () => {
-      it('should not transform the error (no-op for Success)', () => {
-        const result = makeResult.Ok(1).mapError(() => 'new error');
-        expect(unwrap(result)).toBe(1);
-      });
-    });
-
-    describe('match', () => {
-      it('should call ok handler', () => {
-        const result = makeResult.Ok(1);
-        const output = result.match({
-          ok: val => `ok: ${val}`,
-          err: err => `err: ${err}`,
-        });
-        expect(output).toBe('ok: 1');
-      });
-    });
-  });
-
-  describe('Failure methods', () => {
-    describe('map', () => {
-      it('should not transform the value (no-op for Failure)', () => {
-        const result = makeResult.Err('error').map((x: any) => x + 1);
-        expect(isFailure(result)).toBe(true);
-        expect((result as any).error).toBe('error');
-      });
-    });
-
-    describe('chain', () => {
-      it('should not call the function (no-op for Failure)', () => {
-        const fn = vi.fn();
-        const result = makeResult.Err('error').chain(fn);
-        expect(fn).not.toHaveBeenCalled();
-        expect(isFailure(result)).toBe(true);
-      });
-    });
-
-    describe('mapError', () => {
-      it('should transform the error', () => {
-        const result = makeResult.Err('error').mapError(e => e.toUpperCase());
-        expect(isFailure(result)).toBe(true);
-        expect((result as any).error).toBe('ERROR');
-      });
-    });
-
-    describe('match', () => {
-      it('should call err handler', () => {
-        const result = makeResult.Err('error');
-        const output = result.match({
-          ok: val => `ok: ${val}`,
-          err: err => `err: ${err}`,
-        });
-        expect(output).toBe('err: error');
-      });
-    });
-  });
-
-  describe('Edge Cases: Nullish values', () => {
-    it('should handle null as a valid Success value', () => {
-      const result = makeResult.Ok(null);
-      expect(isSuccess(result)).toBe(true);
-      expect(unwrap(result)).toBeNull();
-    });
-
-    it('should handle undefined as a valid Success value', () => {
-      const result = makeResult.Ok(undefined);
-      expect(isSuccess(result)).toBe(true);
-      expect(unwrap(result)).toBeUndefined();
-    });
-
-    it('should allow mapping over null values', () => {
-      const result = makeResult
-        .Ok(null)
-        .map(val => (val === null ? 'was null' : 'not null'));
-      expect(unwrap(result)).toBe('was null');
-    });
-  });
-
-  describe('Control Flow: Exceptions', () => {
-    it('should NOT catch errors thrown inside map (Sync/Pure behavior)', () => {
-      const result = makeResult.Ok(1);
-
-      // If your architecture intends to catch this, change .toThrow() to checking for Err
-      expect(() => {
-        result.map(() => {
-          throw new Error('Boom');
-        });
-      }).toThrow('Boom');
-    });
-
-    it('should NOT catch errors thrown inside chain', () => {
-      const result = makeResult.Ok(1);
-
-      expect(() => {
-        result.chain(() => {
-          throw new Error('Boom');
-        });
-      }).toThrow('Boom');
-    });
-  });
-
-  describe('isResult Edge Cases', () => {
-    it('should return false if type discriminator is invalid', () => {
-      // Has correct shape keys, but wrong 'type' value
-      const fakeResult = { type: 'banana', value: 1 };
-      expect(isResult(fakeResult)).toBe(false);
-    });
-
-    it('should return false for extra properties mimicking result', () => {
-      // Depends on how strict your guard is.
-      // Usually, duck typing accepts this, but good to know.
-      const complicatedObj = { type: 'ok', value: 1, extra: 'stuff' };
-      expect(isResult(complicatedObj)).toBe(true); // Should likely be true
-    });
-  });
-
-  describe('Integration: Pipelining', () => {
-    it('should handle a sequence of maps and chains', () => {
-      const result = makeResult
-        .Ok(10)
-        .map(x => x * 2) // 20
-        .chain(x => makeResult.Ok(x + 5)) // 25
-        .mapError(() => 'new error') // Ignored
-        .map(x => `Value: ${x}`); // "Value: 25"
-
-      expect(unwrap(result)).toBe('Value: 25');
-    });
-
-    it('should short-circuit the pipeline on first error', () => {
-      const fn = vi.fn();
-
-      const result = makeResult
-        .Ok(10)
-        .map(x => x * 2) // 20
-        .chain(() => makeResult.Err('First Failure')) // Breaks here
-        .map(fn) // Should skip
-        .chain(x => makeResult.Ok(x)); // Should skip
-
-      expect(fn).not.toHaveBeenCalled();
-      expect(isFailure(result)).toBe(true);
-      expect((result as any).error).toBe('First Failure');
-    });
-  });
-});