@procedures/collections 0.0.0-stage → 0.1.0

package/src/behaviors/safe.ts

@@ -0,0 +1,372 @@
+/**
+ * Safe behavior - Provides Option/Result-based error handling.
+ *
+ * Wraps collection operations that throw errors to instead return
+ * Option<T> or Result<T, E>, enabling functional error handling.
+ *
+ * @example
+ * const list = compose(
+ *   safeList()
+ * )(arrayList<number>())
+ *
+ * const value = list.safe.get(10) // Option<number> instead of throwing
+ * if (isSome(value)) {
+ *   console.log(value.value)
+ * }
+ */
+
+import type { Middleware } from "../core/middleware.js";
+import type { List } from "../interfaces/list.js";
+import type { Queue, Deque } from "../interfaces/queue.js";
+import type { MapLike } from "../interfaces/map.js";
+import { type Option, type Result } from "../core/effects.js";
+import { None, Some, tryCatch } from "../core/effects.js";
+
+/**
+ * Safe operations for List.
+ */
+export interface SafeListOperations<T> {
+  /**
+   * Get element at index, returning Option.
+   */
+  get(index: number): Option<T>;
+
+  /**
+   * Set element at index, returning Result with old value or error.
+   */
+  set(index: number, element: T): Result<T, string>;
+
+  /**
+   * Remove element at index, returning Result with removed value or error.
+   */
+  removeAt(index: number): Result<T, string>;
+
+  /**
+   * Get first element as Option.
+   */
+  first(): Option<T>;
+
+  /**
+   * Get last element as Option.
+   */
+  last(): Option<T>;
+
+  /**
+   * Pop element, returning Option.
+   */
+  pop(): Option<T>;
+
+  /**
+   * Shift element, returning Option.
+   */
+  shift(): Option<T>;
+}
+
+/**
+ * Safe operations for Queue.
+ */
+export interface SafeQueueOperations<T> {
+  /**
+   * Peek at head element as Option.
+   */
+  peek(): Option<T>;
+
+  /**
+   * Poll element as Option.
+   */
+  poll(): Option<T>;
+
+  /**
+   * Dequeue element as Option.
+   */
+  dequeue(): Option<T>;
+}
+
+/**
+ * Safe operations for Deque.
+ */
+export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
+  /**
+   * Peek at first element as Option.
+   */
+  peekFirst(): Option<T>;
+
+  /**
+   * Peek at last element as Option.
+   */
+  peekLast(): Option<T>;
+
+  /**
+   * Poll first element as Option.
+   */
+  pollFirst(): Option<T>;
+
+  /**
+   * Poll last element as Option.
+   */
+  pollLast(): Option<T>;
+
+  /**
+   * Pop element as Option.
+   */
+  pop(): Option<T>;
+}
+
+/**
+ * Safe operations for Map.
+ */
+export interface SafeMapOperations<K, V> {
+  /**
+   * Get value for key as Option.
+   */
+  get(key: K): Option<V>;
+
+  /**
+   * Set value for key, returning Result with old value or success.
+   */
+  set(key: K, value: V): Result<V | undefined, string>;
+
+  /**
+   * Delete key, returning Result with deleted value or error.
+   */
+  delete(key: K): Result<V | undefined, string>;
+}
+
+/**
+ * Creates a safe List middleware.
+ *
+ * Exposes a `safe` property with Option/Result-based operations.
+ */
+export function safeList<T>(): Middleware<
+  List<T>,
+  List<T> & { safe: SafeListOperations<T> }
+> {
+  return (next: List<T>): List<T> & { safe: SafeListOperations<T> } => {
+    const safe: SafeListOperations<T> = {
+      get(index: number): Option<T> {
+        return tryCatch(
+          () => next.get(index),
+          () => "Index out of bounds"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+
+      set(index: number, element: T): Result<T, string> {
+        return tryCatch(
+          () => next.set(index, element),
+          (error) => String(error)
+        );
+      },
+
+      removeAt(index: number): Result<T, string> {
+        return tryCatch(
+          () => next.removeAt(index),
+          (error) => String(error)
+        );
+      },
+
+      first(): Option<T> {
+        return next.isEmpty ? None : Some(next.first());
+      },
+
+      last(): Option<T> {
+        return next.isEmpty ? None : Some(next.last());
+      },
+
+      pop(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.pop(),
+          () => "List is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+
+      shift(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.shift(),
+          () => "List is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+    };
+
+    // Extend next with safe property
+    return Object.assign(next, { safe });
+  };
+}
+
+/**
+ * Creates a safe Queue middleware.
+ */
+export function safeQueue<T>(): Middleware<
+  Queue<T>,
+  Queue<T> & { safe: SafeQueueOperations<T> }
+> {
+  return (next: Queue<T>): Queue<T> & { safe: SafeQueueOperations<T> } => {
+    const safe: SafeQueueOperations<T> = {
+      peek(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.peek(),
+          () => "Queue is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+
+      poll(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.poll(),
+          () => "Queue is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+
+      dequeue(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.dequeue(),
+          () => "Queue is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+    };
+
+    return Object.assign(next, { safe });
+  };
+}
+
+/**
+ * Creates a safe Deque middleware.
+ */
+export function safeDeque<T>(): Middleware<
+  Deque<T>,
+  Deque<T> & { safe: SafeDequeOperations<T> }
+> {
+  return (next: Deque<T>): Deque<T> & { safe: SafeDequeOperations<T> } => {
+    const safe: SafeDequeOperations<T> = {
+      peek(): Option<T> {
+        return next.isEmpty ? None : Some(next.peekFirst());
+      },
+
+      poll(): Option<T> {
+        // One poll: before, the test and the result each called pollFirst(), so poll() removed
+        // two elements and returned the second (BUGS-2026-07 L12)
+        if (next.isEmpty) return None;
+        return Some(next.pollFirst() as T);
+      },
+
+      dequeue(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.dequeue(),
+          () => "Deque is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+
+      peekFirst(): Option<T> {
+        return next.isEmpty ? None : Some(next.peekFirst());
+      },
+
+      peekLast(): Option<T> {
+        return next.isEmpty ? None : Some(next.peekLast());
+      },
+
+      pollFirst(): Option<T> {
+        const result = next.pollFirst();
+        return result !== undefined ? Some(result) : None;
+      },
+
+      pollLast(): Option<T> {
+        const result = next.pollLast();
+        return result !== undefined ? Some(result) : None;
+      },
+
+      pop(): Option<T> {
+        if (next.isEmpty) return None;
+        return tryCatch(
+          () => next.pop(),
+          () => "Deque is empty"
+        ).match<Option<T>>({
+          Ok: (value) => Some(value),
+          Err: () => None,
+        }) as Option<T>;
+      },
+    };
+
+    return Object.assign(next, { safe });
+  };
+}
+
+/**
+ * Creates a safe Map middleware.
+ */
+export function safeMap<K, V>(): Middleware<
+  MapLike<K, V>,
+  MapLike<K, V> & { safe: SafeMapOperations<K, V> }
+> {
+  return (
+    next: MapLike<K, V>
+  ): MapLike<K, V> & { safe: SafeMapOperations<K, V> } => {
+    const safe: SafeMapOperations<K, V> = {
+      get(key: K): Option<V> {
+        return next.has(key) ? Some(next.get(key)) : None;
+      },
+
+      set(key: K, value: V): Result<V | undefined, string> {
+        return tryCatch(
+          () => next.set(key, value),
+          (error) => String(error)
+        );
+      },
+
+      delete(key: K): Result<V | undefined, string> {
+        return tryCatch(
+          () => next.delete(key),
+          (error) => String(error)
+        );
+      },
+    };
+
+    return Object.assign(next, { safe });
+  };
+}
+
+/**
+ * Helper to match on Result type.
+ * Note: The match method is already built into Ok and Err constructors
+ * in effects.ts, so no runtime augmentation is needed.
+ */
+declare module "../core/effects.js" {
+  interface Ok<T> {
+    match<U>(cases: { Ok: (value: T) => U; Err: (error: never) => U }): U;
+  }
+  interface Err<E> {
+    match<U>(cases: { Ok: (value: never) => U; Err: (error: E) => U }): U;
+  }
+}
+
+/**
+ * Generic safe middleware that works with any collection.
+ */
+export function safe<C extends object>(): Middleware<C> {
+  // Return as-is for now; specialized versions handle specific types
+  return (next: C): C => next;
+}

package/src/behaviors/synchronized.ts

@@ -0,0 +1,316 @@
+/**
+ * Synchronized behavior - Provides thread-safe access with mutex locking.
+ *
+ * Wraps collections to serialize all operations using a mutex, ensuring
+ * thread-safe access in concurrent environments. Mirrors Java's
+ * Collections.synchronizedList() and related methods.
+ *
+ * Note: JavaScript is single-threaded, but async operations can interleave.
+ * This middleware ensures atomic operations across async boundaries.
+ *
+ * @example
+ * const list = compose(
+ *   synchronized()
+ * )(arrayList<number>())
+ *
+ * // All operations are now serialized
+ * await Promise.all([
+ *   list.add(1),
+ *   list.add(2),
+ *   list.add(3)
+ * ])
+ */
+
+import type { Middleware } from "../core/middleware.js";
+
+/**
+ * Simple mutex implementation for JavaScript async operations.
+ *
+ * Ensures that only one operation executes at a time, even if
+ * multiple async operations are initiated concurrently.
+ */
+/** True for an `async` function or method. */
+function isAsyncFunction(value: unknown): boolean {
+  return typeof value === "function" && (value as { [Symbol.toStringTag]?: string })[Symbol.toStringTag] === "AsyncFunction";
+}
+
+class Mutex {
+  private queue: Promise<void> = Promise.resolve();
+
+  /**
+   * Acquires the lock and executes the function.
+   * Other operations wait until this completes.
+   */
+  async lock<T>(fn: () => T | Promise<T>): Promise<T> {
+    const run = this.queue.then(() => fn());
+    this.queue = run.then(
+      () => undefined,
+      () => undefined
+    );
+    return run;
+  }
+
+  /**
+   * Synchronous version that executes immediately.
+   * Still queues to prevent interleaving with async operations.
+   */
+
+}
+
+/**
+ * Creates a synchronized middleware that locks all method calls.
+ *
+ * Every method call on the collection is wrapped with a mutex,
+ * ensuring atomic execution even in concurrent async scenarios.
+ *
+ * @example
+ * const syncList = compose(
+ *   synchronized()
+ * )(arrayList<number>())
+ *
+ * // These additions are guaranteed to execute in order
+ * await Promise.all([
+ *   syncList.add(1),
+ *   syncList.add(2),
+ *   syncList.add(3)
+ * ])
+ */
+export function synchronized<C extends object>(): Middleware<C> {
+  return (next: C): C => {
+    const mutex = new Mutex();
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+
+        // Don't wrap non-functions
+        if (typeof value !== "function") {
+          return value;
+        }
+
+        // An async method runs inside the lock: it starts after the earlier async calls end.
+        // (Before, every method ran first and took the lock after, so nothing was excluded:
+        // BUGS-2026-07 L11.) A plain method runs at once: JavaScript does not interrupt it.
+        // When a plain method returns a promise anyway, the lock waits for that promise.
+        if (isAsyncFunction(value)) {
+          return function (this: unknown, ...args: unknown[]) {
+            return mutex.lock(() => (value as Function).apply(target, args));
+          };
+        }
+        return function (this: unknown, ...args: unknown[]) {
+          const result = (value as Function).apply(target, args);
+          if (result instanceof Promise) {
+            return mutex.lock(() => result);
+          }
+          return result;
+        };
+      },
+    }) as C;
+  };
+}
+
+/**
+ * Alias for Java compatibility: synchronizedList
+ */
+export const synchronizedList : typeof synchronized = synchronized;
+
+/**
+ * Alias for Java compatibility: synchronizedMap
+ */
+export const synchronizedMap : typeof synchronized = synchronized;
+
+/**
+ * Alias for Java compatibility: synchronizedCollection
+ */
+export const synchronizedCollection : typeof synchronized = synchronized;
+
+/**
+ * Alias for Java compatibility: synchronizedSet
+ */
+export const synchronizedSet : typeof synchronized = synchronized;
+
+/**
+ * Advanced synchronized middleware with reentrant locking.
+ *
+ * Allows the same "thread" (async context) to acquire the lock multiple times.
+ * Useful for methods that call other synchronized methods internally.
+ *
+ * Note: JavaScript doesn't have true thread IDs, so we use async context
+ * tracking if available, or fall back to non-reentrant behavior.
+ */
+export function reentrantSynchronized<C extends object>(): Middleware<C> {
+  return (next: C): C => {
+    const mutex = new Mutex();
+    let lockHolder: symbol | null = null;
+    let lockCount = 0;
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+
+        if (typeof value !== "function") {
+          return value;
+        }
+
+        return async function (this: any, ...args: any[]) {
+          // Generate a unique ID for this call context
+          const callerId = Symbol("caller");
+
+          // If we already hold the lock, execute directly (reentrant)
+          if (lockHolder === callerId) {
+            lockCount++;
+            try {
+              const result = (value as Function).apply(target, args);
+              return result instanceof Promise ? await result : result;
+            } finally {
+              lockCount--;
+            }
+          }
+
+          // Otherwise, acquire the lock
+          return mutex.lock(async () => {
+            lockHolder = callerId;
+            lockCount = 1;
+            try {
+              const result = (value as Function).apply(target, args);
+              return result instanceof Promise ? await result : result;
+            } finally {
+              lockCount--;
+              if (lockCount === 0) {
+                lockHolder = null;
+              }
+            }
+          });
+        };
+      },
+    }) as C;
+  };
+}
+
+/**
+ * Read-write lock implementation for collections.
+ *
+ * Allows multiple concurrent readers but exclusive writers.
+ * More efficient than full synchronization for read-heavy workloads.
+ *
+ * @example
+ * const list = compose(
+ *   readWriteLock()
+ * )(arrayList<number>())
+ *
+ * // Multiple reads can happen concurrently
+ * await Promise.all([
+ *   list.get(0),
+ *   list.get(1),
+ *   list.get(2)
+ * ])
+ */
+export function readWriteLock<C extends object>(): Middleware<C> {
+  return (next: C): C => {
+    let readers = 0;
+    let writer = false;
+    let waitingReaders: (() => void)[] = [];
+    let waitingWriters: (() => void)[] = [];
+
+    // Hand-off rule: the releaser counts the waiters it wakes (readers += n, or writer = true),
+    // so a woken waiter does not count itself again. (Before, releaseWrite set readers = n and
+    // each woken reader added 1, so the count never came back to 0 and writers waited forever:
+    // BUGS-2026-07 L11.)
+    const acquireRead = async (): Promise<void> => {
+      if (writer || waitingWriters.length > 0) {
+        await new Promise<void>((resolve) => waitingReaders.push(resolve));
+        return;
+      }
+      readers++;
+    };
+
+    const releaseRead = (): void => {
+      readers--;
+      if (readers === 0 && waitingWriters.length > 0) {
+        writer = true;
+        const next = waitingWriters.shift()!;
+        next();
+      }
+    };
+
+    const acquireWrite = async (): Promise<void> => {
+      if (writer || readers > 0) {
+        await new Promise<void>((resolve) => waitingWriters.push(resolve));
+        return;
+      }
+      writer = true;
+    };
+
+    const releaseWrite = (): void => {
+      writer = false;
+      if (waitingWriters.length > 0) {
+        writer = true;
+        const next = waitingWriters.shift()!;
+        next();
+      } else if (waitingReaders.length > 0) {
+        const allReaders = waitingReaders.splice(0);
+        readers += allReaders.length;
+        allReaders.forEach((resolve) => resolve());
+      }
+    };
+
+    // Methods that only read (don't mutate)
+    const READ_METHODS = new Set([
+      "get",
+      "has",
+      "contains",
+      "containsAll",
+      "containsValue",
+      "indexOf",
+      "lastIndexOf",
+      "peek",
+      "peekFirst",
+      "peekLast",
+      "first",
+      "last",
+      "isEmpty",
+      "size",
+      "toArray",
+      "keys",
+      "values",
+      "entries",
+      "forEach",
+      "getOrDefault",
+      "getOrUndefined",
+    ]);
+
+    return new Proxy(next, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+
+        if (typeof value !== "function") {
+          return value;
+        }
+
+        const isReadMethod = typeof prop === "string" && READ_METHODS.has(prop);
+
+        return async function (this: any, ...args: any[]) {
+          if (isReadMethod) {
+            // Acquire read lock
+            await acquireRead();
+            try {
+              const result = (value as Function).apply(target, args);
+              return result instanceof Promise ? await result : result;
+            } finally {
+              releaseRead();
+            }
+          } else {
+            // Acquire write lock
+            await acquireWrite();
+            try {
+              const result = (value as Function).apply(target, args);
+              return result instanceof Promise ? await result : result;
+            } finally {
+              releaseWrite();
+            }
+          }
+        };
+      },
+    }) as C;
+  };
+}