vest-utils 1.5.0 → 2.0.2

package/src/Result.ts

@@ -0,0 +1,121 @@
+import { isObject } from './valueIsObject';
+
+export type Result<T, E = unknown> = Success<T, E> | Failure<T, E>;
+
+type Success<T, E> = {
+  chain<U, E2 = E>(fn: (value: T) => Result<U, E2>): Result<U, E | E2>;
+  map<U>(fn: (value: T) => U): Result<U, E>;
+  mapError<E2>(fn: (error: E) => E2): Result<T, E2>;
+  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U;
+  readonly type: 'ok';
+  unwrap(): T;
+  unwrapOr(defaultValue: T): T;
+  readonly value: T;
+};
+
+export type Failure<T, E> = {
+  chain<U, E2 = E>(fn: (value: T) => Result<U, E2>): Result<U, E | E2>;
+  readonly error: E;
+  map<U>(fn: (value: T) => U): Result<U, E>;
+  mapError<E2>(fn: (error: E) => E2): Result<T, E2>;
+  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U;
+  readonly type: 'err';
+  unwrap(): T;
+  unwrapOr(defaultValue: T): T;
+};
+
+function ok<T, E = unknown>(value: T): Success<T, E> {
+  return {
+    chain<U, E2 = E>(fn: (inner: T) => Result<U, E2>) {
+      return fn(value) as Result<U, E | E2>;
+    },
+    map<U>(fn: (inner: T) => U) {
+      return ok<U, E>(fn(value));
+    },
+    mapError<E2>(_fn: (error: E) => E2) {
+      return this as unknown as Success<T, E2>;
+    },
+    match<U>(handlers: { ok: (val: T) => U; err: (err: E) => U }) {
+      return handlers.ok(value);
+    },
+    type: 'ok',
+    unwrap() {
+      return value;
+    },
+    unwrapOr(_defaultValue: T) {
+      return value;
+    },
+    value,
+  };
+}
+
+function err<T = never, E = unknown>(error: E): Failure<T, E> {
+  return {
+    chain<U, E2 = E>(_fn: (inner: T) => Result<U, E2>) {
+      return this as unknown as Failure<U, E | E2>;
+    },
+    error,
+    map<U>(_fn: (inner: T) => U) {
+      return this as unknown as Failure<U, E>;
+    },
+    mapError<E2>(fn: (inner: E) => E2) {
+      return err<T, E2>(fn(error));
+    },
+    match<U>(handlers: { ok: (val: T) => U; err: (err: E) => U }) {
+      return handlers.err(error);
+    },
+    type: 'err',
+    unwrap() {
+      throw error instanceof Error ? error : new Error(String(error));
+    },
+    unwrapOr(defaultValue: T) {
+      return defaultValue;
+    },
+  };
+}
+
+export const makeResult = { Ok: ok, Err: err } as const;
+
+const hasResultType = (candidate: { type?: unknown }): boolean =>
+  candidate.type === 'ok' || candidate.type === 'err';
+
+const hasResultShape = (candidate: Record<string, unknown>): boolean =>
+  'value' in candidate || 'error' in candidate;
+
+export function isResult(value: unknown): value is Result<unknown, unknown> {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  const candidate = value as { type?: unknown } & Record<string, unknown>;
+
+  if (!hasResultShape(candidate)) {
+    return false;
+  }
+
+  return hasResultType(candidate);
+}
+
+export function isSuccess<T, E>(value: Result<T, E>): value is Success<T, E> {
+  return value.type === 'ok';
+}
+
+export function isFailure<T, E>(value: Result<T, E>): value is Failure<T, E> {
+  return value.type === 'err';
+}
+
+/**
+ * Unwraps a Result.
+ * If the Result is Success, it returns the value.
+ * If the Result is Failure, it throws the error.
+ */
+export function unwrap<T>(result: Result<T, any>): T {
+  if (isFailure(result)) {
+    // Ensure we always throw an Error object for better stack traces
+    throw result.error instanceof Error
+      ? result.error
+      : new Error(String(result.error));
+  }
+
+  return result.value;
+}

package/src/SimpleStateMachine.ts

@@ -0,0 +1,157 @@
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,118 @@
+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);
+    });
+  });
+});