@procedures/collections 0.0.0-stage → 0.2.0

package/src/core/effects.ts

@@ -0,0 +1,323 @@
+/**
+ * Functional effect types for error handling and optional values.
+ *
+ * Provides Option<T> and Result<T,E> types for explicit, type-safe
+ * error handling without exceptions. Includes async variants.
+ */
+
+// ============================================================================
+// Option<T> - represents optional values
+// ============================================================================
+
+/**
+ * Represents the absence of a value.
+ */
+export interface None {
+  readonly _tag: "None";
+}
+
+/**
+ * Represents the presence of a value.
+ */
+export interface Some<T> {
+  readonly _tag: "Some";
+  readonly value: T;
+}
+
+/**
+ * Option<T> represents a value that may or may not be present.
+ * This is a type-safe alternative to null/undefined.
+ *
+ * @example
+ * function findUser(id: string): Option<User> {
+ *   const user = db.get(id);
+ *   return user ? Some(user) : None;
+ * }
+ */
+export type Option<T> = None | Some<T>;
+
+/**
+ * The singleton None value.
+ */
+export const None: None = Object.freeze({ _tag: "None" });
+
+/**
+ * Constructs a Some value containing the given value.
+ */
+export const Some = <T>(value: T): Some<T> =>
+  Object.freeze({ _tag: "Some", value });
+
+/**
+ * Type guard to check if an Option is None.
+ */
+export const isNone = <T>(opt: Option<T>): opt is None => opt._tag === "None";
+
+/**
+ * Type guard to check if an Option is Some.
+ */
+export const isSome = <T>(opt: Option<T>): opt is Some<T> =>
+  opt._tag === "Some";
+
+/**
+ * Extracts the value from a Some, or returns the default value if None.
+ */
+export const getOrElse = <T>(opt: Option<T>, defaultValue: T): T =>
+  isSome(opt) ? opt.value : defaultValue;
+
+/**
+ * Extracts the value from a Some, or throws an error if None.
+ */
+export const unwrap = <T>(opt: Option<T>): T => {
+  if (isSome(opt)) return opt.value;
+  throw new Error("Called unwrap on None");
+};
+
+/**
+ * Maps a function over the value in a Some, or returns None.
+ */
+export const mapOption = <T, U>(
+  opt: Option<T>,
+  f: (value: T) => U
+): Option<U> => (isSome(opt) ? Some(f(opt.value)) : None);
+
+/**
+ * Chains Option-returning operations.
+ */
+export const flatMapOption = <T, U>(
+  opt: Option<T>,
+  f: (value: T) => Option<U>
+): Option<U> => (isSome(opt) ? f(opt.value) : None);
+
+/**
+ * Converts a nullable value to an Option.
+ */
+export const fromNullable = <T>(value: T | null | undefined): Option<T> =>
+  value == null ? None : Some(value);
+
+/**
+ * Converts an Option to a nullable value.
+ */
+export const toNullable = <T>(opt: Option<T>): T | undefined =>
+  isSome(opt) ? opt.value : undefined;
+
+// ============================================================================
+// Result<T, E> - represents success or failure
+// ============================================================================
+
+/**
+ * Represents a successful result containing a value.
+ */
+export interface Ok<T> {
+  readonly _tag: "Ok";
+  readonly value: T;
+}
+
+/**
+ * Represents a failed result containing an error.
+ */
+export interface Err<E> {
+  readonly _tag: "Err";
+  readonly error: E;
+}
+
+/**
+ * Result<T, E> represents the result of an operation that may fail.
+ * It contains either a success value (Ok) or an error value (Err).
+ *
+ * @example
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return Err("Division by zero");
+ *   return Ok(a / b);
+ * }
+ */
+export type Result<T, E> = Ok<T> | Err<E>;
+
+/**
+ * Constructs an Ok result containing the given value.
+ */
+export const Ok = <T>(value: T): Ok<T> =>
+  Object.freeze({
+    _tag: "Ok",
+    value,
+    match: <U>(f: { Ok: (value: T) => U; Err: (error: unknown) => U }) =>
+      f.Ok(value),
+  });
+
+/**
+ * Constructs an Err result containing the given error.
+ */
+export const Err = <E>(error: E): Err<E> =>
+  Object.freeze({
+    _tag: "Err",
+    error,
+    match: <U>(f: { Ok: (value: unknown) => U; Err: (error: E) => U }) =>
+      f.Err(error),
+  });
+
+/**
+ * Type guard to check if a Result is Ok.
+ */
+export const isOk = <T, E>(result: Result<T, E>): result is Ok<T> =>
+  result._tag === "Ok";
+
+/**
+ * Type guard to check if a Result is Err.
+ */
+export const isErr = <T, E>(result: Result<T, E>): result is Err<E> =>
+  result._tag === "Err";
+
+/**
+ * Extracts the value from an Ok, or returns the default value if Err.
+ */
+export const getOrElseResult = <T, E>(
+  result: Result<T, E>,
+  defaultValue: T
+): T => (isOk(result) ? result.value : defaultValue);
+
+/**
+ * Extracts the value from an Ok, or throws the error if Err.
+ */
+export const unwrapResult = <T, E>(result: Result<T, E>): T => {
+  if (isOk(result)) return result.value;
+  throw result.error;
+};
+
+/**
+ * Maps a function over the value in an Ok, or returns the Err unchanged.
+ */
+export const mapResult = <T, U, E>(
+  result: Result<T, E>,
+  f: (value: T) => U
+): Result<U, E> => (isOk(result) ? Ok(f(result.value)) : result);
+
+/**
+ * Maps a function over the error in an Err, or returns the Ok unchanged.
+ */
+export const mapError = <T, E, F>(
+  result: Result<T, E>,
+  f: (error: E) => F
+): Result<T, F> => (isErr(result) ? Err(f(result.error)) : result);
+
+/**
+ * Chains Result-returning operations.
+ */
+export const flatMapResult = <T, U, E>(
+  result: Result<T, E>,
+  f: (value: T) => Result<U, E>
+): Result<U, E> => (isOk(result) ? f(result.value) : result);
+
+/**
+ * Converts a throwing function into a Result-returning function.
+ */
+export const tryCatch = <T, E = unknown>(
+  fn: () => T,
+  onError?: (error: unknown) => E
+): Result<T, E> => {
+  try {
+    return Ok(fn());
+  } catch (error) {
+    return Err((onError ? onError(error) : error) as E);
+  }
+};
+
+/**
+ * Converts an async throwing function into a Result-returning async function.
+ */
+export const tryCatchAsync = async <T, E = unknown>(
+  fn: () => Promise<T>,
+  onError?: (error: unknown) => E
+): Promise<Result<T, E>> => {
+  try {
+    return Ok(await fn());
+  } catch (error) {
+    return Err((onError ? onError(error) : error) as E);
+  }
+};
+
+// ============================================================================
+// Async variants
+// ============================================================================
+
+/**
+ * Async variant of Option<T>.
+ */
+export type AsyncOption<T> = Promise<Option<T>>;
+
+/**
+ * Async variant of Result<T, E>.
+ */
+export type AsyncResult<T, E> = Promise<Result<T, E>>;
+
+/**
+ * Maps a function over an async Option.
+ */
+export const mapAsyncOption = async <T, U>(
+  opt: AsyncOption<T>,
+  f: (value: T) => U | Promise<U>
+): AsyncOption<U> => {
+  const resolved = await opt;
+  if (isSome(resolved)) {
+    return Some(await f(resolved.value));
+  }
+  return None;
+};
+
+/**
+ * Maps a function over an async Result.
+ */
+export const mapAsyncResult = async <T, U, E>(
+  result: AsyncResult<T, E>,
+  f: (value: T) => U | Promise<U>
+): AsyncResult<U, E> => {
+  const resolved = await result;
+  if (isOk(resolved)) {
+    return Ok(await f(resolved.value));
+  }
+  return resolved;
+};
+
+// ============================================================================
+// Conversion utilities
+// ============================================================================
+
+/**
+ * Converts an Option to a Result.
+ * None becomes Err with the provided error.
+ */
+export const optionToResult = <T, E>(opt: Option<T>, error: E): Result<T, E> =>
+  isSome(opt) ? Ok(opt.value) : Err(error);
+
+/**
+ * Converts a Result to an Option.
+ * Err becomes None, discarding the error.
+ */
+export const resultToOption = <T, E>(result: Result<T, E>): Option<T> =>
+  isOk(result) ? Some(result.value) : None;
+
+/**
+ * Combines multiple Options into an Option of an array.
+ * Returns None if any input is None.
+ */
+export const sequence = <T>(opts: Option<T>[]): Option<T[]> => {
+  const values: T[] = [];
+  for (const opt of opts) {
+    if (isNone(opt)) return None;
+    values.push(opt.value);
+  }
+  return Some(values);
+};
+
+/**
+ * Combines multiple Results into a Result of an array.
+ * Returns the first Err encountered, or Ok with all values.
+ */
+export const sequenceResults = <T, E>(
+  results: Result<T, E>[]
+): Result<T[], E> => {
+  const values: T[] = [];
+  for (const result of results) {
+    if (isErr(result)) return result;
+    values.push(result.value);
+  }
+  return Ok(values);
+};

package/src/core/events.ts

@@ -0,0 +1,356 @@
+/**
+ * Typed event emitter system for collections.
+ *
+ * Provides a lightweight, type-safe event system for mutation events
+ * and other observable behavior. Events are strongly typed using
+ * TypeScript's mapped types.
+ */
+
+/**
+ * A listener function that receives an event payload.
+ */
+export type Listener<P> = (payload: P) => void;
+
+/**
+ * A function to unsubscribe from an event.
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Event map defining event names and their payload types.
+ *
+ * @example
+ * interface MyEvents {
+ *   add: { value: number; index: number }
+ *   remove: { value: number }
+ *   clear: {}
+ * }
+ */
+export type EventMap = Record<string, any>;
+
+/**
+ * Type-safe event emitter.
+ *
+ * Supports subscribing to events, emitting events, and managing listeners.
+ * All event names and payloads are type-checked at compile time.
+ *
+ * @example
+ * interface ListEvents<T> {
+ *   add: { value: T; index: number }
+ *   remove: { value: T; index: number }
+ *   clear: {}
+ * }
+ *
+ * const emitter = new Emitter<ListEvents<number>>()
+ *
+ * const unsub = emitter.on('add', ({ value, index }) => {
+ *   console.log(`Added ${value} at ${index}`)
+ * })
+ *
+ * emitter.emit('add', { value: 42, index: 0 })
+ * unsub() // Unsubscribe
+ */
+export class Emitter<E extends EventMap> {
+  private listeners = new Map<keyof E, Set<Listener<any>>>();
+
+  /**
+   * Subscribe to an event.
+   *
+   * @param event The event name
+   * @param listener The callback to invoke when event is emitted
+   * @returns A function to unsubscribe
+   */
+  on<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe {
+    let listeners = this.listeners.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.listeners.set(event, listeners);
+    }
+    listeners.add(listener);
+
+    // Return unsubscribe function
+    return () => {
+      listeners!.delete(listener);
+      // Clean up empty sets
+      if (listeners!.size === 0) {
+        this.listeners.delete(event);
+      }
+    };
+  }
+
+  /**
+   * Subscribe to an event, but automatically unsubscribe after first emission.
+   *
+   * @param event The event name
+   * @param listener The callback to invoke once
+   * @returns A function to unsubscribe (in case you want to cancel before emission)
+   */
+  once<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe {
+    const wrappedListener: Listener<E[K]> = (payload) => {
+      unsubscribe();
+      listener(payload);
+    };
+
+    const unsubscribe = this.on(event, wrappedListener);
+    return unsubscribe;
+  }
+
+  /**
+   * Emit an event to all registered listeners.
+   *
+   * @param event The event name
+   * @param payload The event payload
+   */
+  emit<K extends keyof E>(event: K, payload: E[K]): void {
+    const listeners = this.listeners.get(event);
+    if (listeners) {
+      // Create a snapshot to avoid issues if listeners modify the set
+      const snapshot = Array.from(listeners);
+      for (const listener of snapshot) {
+        try {
+          listener(payload);
+        } catch (error) {
+          // Log error but don't stop other listeners
+          console.error(
+            `Error in event listener for '${String(event)}':`,
+            error
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Remove all listeners for a specific event, or all events if no event specified.
+   *
+   * @param event Optional event name to clear listeners for
+   */
+  off<K extends keyof E>(event?: K): void {
+    if (event !== undefined) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  /**
+   * Get the number of listeners for a specific event.
+   *
+   * @param event The event name
+   * @returns Number of registered listeners
+   */
+  listenerCount<K extends keyof E>(event: K): number {
+    return this.listeners.get(event)?.size ?? 0;
+  }
+
+  /**
+   * Get all event names that have at least one listener.
+   */
+  eventNames(): (keyof E)[] {
+    return Array.from(this.listeners.keys());
+  }
+
+  /**
+   * Check if there are any listeners for a specific event.
+   */
+  hasListeners<K extends keyof E>(event: K): boolean {
+    return this.listenerCount(event) > 0;
+  }
+
+  /**
+   * Remove all listeners and clean up resources.
+   */
+  dispose(): void {
+    this.listeners.clear();
+  }
+}
+
+/**
+ * Create an event emitter for a specific event map.
+ *
+ * This is a convenience factory function.
+ *
+ * @example
+ * const events = createEmitter<ListEvents<number>>()
+ */
+export const createEmitter = <E extends EventMap>(): Emitter<E> => {
+  return new Emitter<E>();
+};
+
+/**
+ * Event batching utility for reducing event noise.
+ * Collects events and emits them in batches.
+ *
+ * @example
+ * const batcher = new EventBatcher(emitter, 'add', 100)
+ * batcher.queue({ value: 1, index: 0 })
+ * batcher.queue({ value: 2, index: 1 })
+ * // After 100ms or flush(), emits single 'batch-add' event with both items
+ */
+export class EventBatcher<E extends EventMap, K extends keyof E> {
+  private batch: E[K][] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private emitter: Emitter<E & { [P in `batch-${K & string}`]: E[K][] }>,
+    private event: K,
+    private delayMs: number
+  ) {}
+
+  /**
+   * Add an event to the current batch.
+   */
+  queue(payload: E[K]): void {
+    this.batch.push(payload);
+
+    if (this.timer === null) {
+      this.timer = setTimeout(() => this.flush(), this.delayMs);
+    }
+  }
+
+  /**
+   * Immediately emit all batched events.
+   */
+  flush(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    if (this.batch.length > 0) {
+      const batchEvent = `batch-${String(this.event)}` as keyof (E & { [P in `batch-${K & string}`]: E[K][] });
+      this.emitter.emit(batchEvent, this.batch as any);
+      this.batch = [];
+    }
+  }
+
+  /**
+   * Clean up resources.
+   */
+  dispose(): void {
+    this.flush();
+  }
+}
+
+/**
+ * Async event emitter that returns promises.
+ * Waits for all async listeners to complete.
+ *
+ * @example
+ * const emitter = new AsyncEmitter<{ save: { data: string } }>()
+ *
+ * emitter.on('save', async ({ data }) => {
+ *   await database.save(data)
+ * })
+ *
+ * await emitter.emit('save', { data: 'test' }) // Waits for save
+ */
+export class AsyncEmitter<E extends EventMap> {
+  private listeners = new Map<keyof E, Set<Listener<any>>>();
+
+  on<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe {
+    let listeners = this.listeners.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.listeners.set(event, listeners);
+    }
+    listeners.add(listener);
+
+    return () => {
+      listeners!.delete(listener);
+      if (listeners!.size === 0) {
+        this.listeners.delete(event);
+      }
+    };
+  }
+
+  /**
+   * Emit an event and wait for all async listeners to complete.
+   *
+   * @param event The event name
+   * @param payload The event payload
+   * @returns Promise that resolves when all listeners complete
+   */
+  async emit<K extends keyof E>(event: K, payload: E[K]): Promise<void> {
+    const listeners = this.listeners.get(event);
+    if (listeners) {
+      const promises = Array.from(listeners).map((listener) =>
+        Promise.resolve().then(() => listener(payload))
+      );
+      await Promise.all(promises);
+    }
+  }
+
+  off<K extends keyof E>(event?: K): void {
+    if (event !== undefined) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+  }
+
+  listenerCount<K extends keyof E>(event: K): number {
+    return this.listeners.get(event)?.size ?? 0;
+  }
+
+  eventNames(): (keyof E)[] {
+    return Array.from(this.listeners.keys());
+  }
+
+  dispose(): void {
+    this.listeners.clear();
+  }
+}
+
+/**
+ * Utility to forward events from one emitter to another.
+ * Useful for composing event sources.
+ *
+ * @example
+ * const child = new Emitter<ChildEvents>()
+ * const parent = new Emitter<ParentEvents>()
+ *
+ * forwardEvent(child, parent, 'childEvent', 'parentEvent')
+ */
+export const forwardEvent = <
+  E1 extends EventMap,
+  E2 extends EventMap,
+  K1 extends keyof E1,
+  K2 extends keyof E2
+>(
+  source: Emitter<E1>,
+  target: Emitter<E2>,
+  sourceEvent: K1,
+  targetEvent: K2,
+  transform?: (payload: E1[K1]) => E2[K2]
+): Unsubscribe => {
+  return source.on(sourceEvent, (payload) => {
+    const transformedPayload = transform
+      ? transform(payload)
+      : (payload as any);
+    target.emit(targetEvent, transformedPayload);
+  });
+};
+
+/**
+ * Create a filtered event subscription that only fires when predicate is true.
+ *
+ * @example
+ * const emitter = new Emitter<{ change: { value: number } }>()
+ *
+ * onWhen(emitter, 'change', ({ value }) => value > 10, ({ value }) => {
+ *   console.log('Value exceeded 10:', value)
+ * })
+ */
+export const onWhen = <E extends EventMap, K extends keyof E>(
+  emitter: Emitter<E>,
+  event: K,
+  predicate: (payload: E[K]) => boolean,
+  listener: Listener<E[K]>
+): Unsubscribe => {
+  return emitter.on(event, (payload) => {
+    if (predicate(payload)) {
+      listener(payload);
+    }
+  });
+};