@procedures/client 0.0.0-stage → 0.2.0

package/dist/collections/behaviors/ttl.js

@@ -0,0 +1,338 @@
+/**
+ * TTL (Time-To-Live) expiration behavior.
+ *
+ * Automatically expires elements after a specified time period.
+ * Perfect for temporary caches and time-limited data.
+ *
+ * @example
+ * const cache = compose(
+ *   ttlMap({ ttl: 60000 }) // 60 seconds
+ * )(hashMap<string, Data>())
+ *
+ * cache.set('key', data)
+ * // After 60 seconds, 'key' is automatically removed
+ */
+/**
+ * Creates a TTL Map middleware.
+ *
+ * Automatically removes entries after TTL expires.
+ * Uses a background interval to check for expired entries.
+ */
+export function ttlMap(options) {
+    const { ttl, checkInterval = 1000, onExpire } = options;
+    return (next) => {
+        const metadata = new Map();
+        let intervalId = null;
+        const checkExpired = () => {
+            const now = Date.now();
+            const expired = [];
+            for (const [key, entry] of metadata) {
+                if (now >= entry.expiresAt) {
+                    expired.push(key);
+                }
+            }
+            for (const key of expired) {
+                const entry = metadata.get(key);
+                if (entry) {
+                    next.delete(key);
+                    metadata.delete(key);
+                    if (onExpire) {
+                        onExpire({
+                            key,
+                            value: entry.value,
+                            createdAt: entry.createdAt,
+                            expiredAt: now,
+                        });
+                    }
+                }
+            }
+        };
+        // Start background expiration checker
+        intervalId = setInterval(checkExpired, checkInterval);
+        const dispose = () => {
+            if (intervalId) {
+                clearInterval(intervalId);
+                intervalId = null;
+            }
+        };
+        return new Proxy(next, {
+            get(target, prop, receiver) {
+                // Add dispose method
+                if (prop === "dispose") {
+                    return dispose;
+                }
+                const value = Reflect.get(target, prop, receiver);
+                if (typeof value === "function") {
+                    switch (prop) {
+                        case "get":
+                            return function (key) {
+                                // Check if expired before returning
+                                const entry = metadata.get(key);
+                                if (entry && Date.now() >= entry.expiresAt) {
+                                    target.delete(key);
+                                    metadata.delete(key);
+                                    throw new Error(`Key expired: ${key}`);
+                                }
+                                return value.call(target, key);
+                            };
+                        case "has":
+                            return function (key) {
+                                // Check if expired
+                                const entry = metadata.get(key);
+                                if (entry && Date.now() >= entry.expiresAt) {
+                                    target.delete(key);
+                                    metadata.delete(key);
+                                    return false;
+                                }
+                                return value.call(target, key);
+                            };
+                        case "set":
+                            return function (key, val) {
+                                const now = Date.now();
+                                const result = value.call(target, key, val);
+                                metadata.set(key, {
+                                    value: val,
+                                    expiresAt: now + ttl,
+                                    createdAt: now,
+                                });
+                                return result;
+                            };
+                        case "delete":
+                            return function (key) {
+                                const result = value.call(target, key);
+                                metadata.delete(key);
+                                return result;
+                            };
+                        case "clear":
+                            return function () {
+                                value.call(target);
+                                metadata.clear();
+                            };
+                    }
+                }
+                return value;
+            },
+        });
+    };
+}
+/**
+ * Creates a TTL Collection middleware.
+ *
+ * Note: This is less precise than TTL map because collections don't have keys.
+ * Elements are tracked by reference, which may not work for primitive types.
+ */
+export function ttlCollection(options) {
+    const { ttl, checkInterval = 1000, onExpire } = options;
+    return (next) => {
+        const metadata = new Map();
+        let intervalId = null;
+        const checkExpired = () => {
+            const now = Date.now();
+            const expired = [];
+            for (const [element, entry] of metadata) {
+                if (now >= entry.expiresAt) {
+                    expired.push(element);
+                }
+            }
+            for (const element of expired) {
+                const entry = metadata.get(element);
+                if (entry) {
+                    next.remove(element);
+                    metadata.delete(element);
+                    if (onExpire) {
+                        onExpire({
+                            element,
+                            createdAt: entry.createdAt,
+                            expiredAt: now,
+                        });
+                    }
+                }
+            }
+        };
+        intervalId = setInterval(checkExpired, checkInterval);
+        const dispose = () => {
+            if (intervalId) {
+                clearInterval(intervalId);
+                intervalId = null;
+            }
+        };
+        return new Proxy(next, {
+            get(target, prop, receiver) {
+                if (prop === "dispose") {
+                    return dispose;
+                }
+                const value = Reflect.get(target, prop, receiver);
+                if (typeof value === "function") {
+                    switch (prop) {
+                        case "add":
+                            return function (element) {
+                                const result = value.call(target, element);
+                                if (result) {
+                                    const now = Date.now();
+                                    metadata.set(element, {
+                                        expiresAt: now + ttl,
+                                        createdAt: now,
+                                    });
+                                }
+                                return result;
+                            };
+                        case "remove":
+                            return function (element) {
+                                const result = value.call(target, element);
+                                if (result) {
+                                    metadata.delete(element);
+                                }
+                                return result;
+                            };
+                        case "clear":
+                            return function () {
+                                value.call(target);
+                                metadata.clear();
+                            };
+                    }
+                }
+                return value;
+            },
+        });
+    };
+}
+/**
+ * Standalone TTL cache with Map-like API.
+ *
+ * @example
+ * const cache = new TTLCache<string, number>(60000) // 60 second TTL
+ * cache.set('key', 42)
+ * setTimeout(() => {
+ *   cache.get('key') // undefined (expired)
+ * }, 61000)
+ */
+export class TTLCache {
+    ttl;
+    checkInterval;
+    onExpire;
+    map = new Map();
+    intervalId = null;
+    constructor(ttl, checkInterval = 1000, onExpire) {
+        this.ttl = ttl;
+        this.checkInterval = checkInterval;
+        this.onExpire = onExpire;
+        this.startExpirationCheck();
+    }
+    get size() {
+        this.cleanup();
+        return this.map.size;
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() >= entry.expiresAt) {
+            this.map.delete(key);
+            if (this.onExpire) {
+                this.onExpire(key, entry.value);
+            }
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, customTTL) {
+        const now = Date.now();
+        const ttlToUse = customTTL !== undefined ? customTTL : this.ttl;
+        this.map.set(key, {
+            value,
+            expiresAt: now + ttlToUse,
+            createdAt: now,
+        });
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+    /**
+     * Manually trigger cleanup of expired entries.
+     */
+    cleanup() {
+        const now = Date.now();
+        const expired = [];
+        for (const [key, entry] of this.map) {
+            if (now >= entry.expiresAt) {
+                expired.push(key);
+            }
+        }
+        for (const key of expired) {
+            const entry = this.map.get(key);
+            if (entry) {
+                this.map.delete(key);
+                if (this.onExpire) {
+                    this.onExpire(key, entry.value);
+                }
+            }
+        }
+    }
+    /**
+     * Get remaining TTL for a key in milliseconds.
+     * Returns undefined if key doesn't exist or is expired.
+     */
+    getTTL(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        const remaining = entry.expiresAt - Date.now();
+        return remaining > 0 ? remaining : undefined;
+    }
+    /**
+     * Update TTL for an existing key.
+     */
+    touch(key, customTTL) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() >= entry.expiresAt) {
+            this.map.delete(key);
+            return false;
+        }
+        const ttlToUse = customTTL !== undefined ? customTTL : this.ttl;
+        entry.expiresAt = Date.now() + ttlToUse;
+        return true;
+    }
+    startExpirationCheck() {
+        this.intervalId = setInterval(() => this.cleanup(), this.checkInterval);
+    }
+    /**
+     * Stop the background expiration checker and clean up.
+     */
+    dispose() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    *keys() {
+        this.cleanup();
+        yield* this.map.keys();
+    }
+    *values() {
+        this.cleanup();
+        for (const entry of this.map.values()) {
+            yield entry.value;
+        }
+    }
+    *entries() {
+        this.cleanup();
+        for (const [key, entry] of this.map) {
+            yield [key, entry.value];
+        }
+    }
+}
+/**
+ * Factory function to create a TTL cache.
+ */
+export function ttlCache(ttl, options) {
+    return new TTLCache(ttl, options?.checkInterval, options?.onExpire);
+}
+//# sourceMappingURL=ttl.js.map

package/dist/collections/behaviors/ttl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttl.js","sourceRoot":"","sources":["../../../src/collections/behaviors/ttl.ts"],"names":[],"mappings":"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"}

package/dist/collections/core/effects.d.ts

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const None: None;
+/**
+ * Constructs a Some value containing the given value.
+ */
+export declare const Some: <T>(value: T) => Some<T>;
+/**
+ * Type guard to check if an Option is None.
+ */
+export declare const isNone: <T>(opt: Option<T>) => opt is None;
+/**
+ * Type guard to check if an Option is Some.
+ */
+export declare const isSome: <T>(opt: Option<T>) => opt is Some<T>;
+/**
+ * Extracts the value from a Some, or returns the default value if None.
+ */
+export declare const getOrElse: <T>(opt: Option<T>, defaultValue: T) => T;
+/**
+ * Extracts the value from a Some, or throws an error if None.
+ */
+export declare const unwrap: <T>(opt: Option<T>) => T;
+/**
+ * Maps a function over the value in a Some, or returns None.
+ */
+export declare const mapOption: <T, U>(opt: Option<T>, f: (value: T) => U) => Option<U>;
+/**
+ * Chains Option-returning operations.
+ */
+export declare const flatMapOption: <T, U>(opt: Option<T>, f: (value: T) => Option<U>) => Option<U>;
+/**
+ * Converts a nullable value to an Option.
+ */
+export declare const fromNullable: <T>(value: T | null | undefined) => Option<T>;
+/**
+ * Converts an Option to a nullable value.
+ */
+export declare const toNullable: <T>(opt: Option<T>) => T | undefined;
+/**
+ * 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 declare const Ok: <T>(value: T) => Ok<T>;
+/**
+ * Constructs an Err result containing the given error.
+ */
+export declare const Err: <E>(error: E) => Err<E>;
+/**
+ * Type guard to check if a Result is Ok.
+ */
+export declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T>;
+/**
+ * Type guard to check if a Result is Err.
+ */
+export declare const isErr: <T, E>(result: Result<T, E>) => result is Err<E>;
+/**
+ * Extracts the value from an Ok, or returns the default value if Err.
+ */
+export declare const getOrElseResult: <T, E>(result: Result<T, E>, defaultValue: T) => T;
+/**
+ * Extracts the value from an Ok, or throws the error if Err.
+ */
+export declare const unwrapResult: <T, E>(result: Result<T, E>) => T;
+/**
+ * Maps a function over the value in an Ok, or returns the Err unchanged.
+ */
+export declare const mapResult: <T, U, E>(result: Result<T, E>, f: (value: T) => U) => Result<U, E>;
+/**
+ * Maps a function over the error in an Err, or returns the Ok unchanged.
+ */
+export declare const mapError: <T, E, F>(result: Result<T, E>, f: (error: E) => F) => Result<T, F>;
+/**
+ * Chains Result-returning operations.
+ */
+export declare const flatMapResult: <T, U, E>(result: Result<T, E>, f: (value: T) => Result<U, E>) => Result<U, E>;
+/**
+ * Converts a throwing function into a Result-returning function.
+ */
+export declare const tryCatch: <T, E = unknown>(fn: () => T, onError?: (error: unknown) => E) => Result<T, E>;
+/**
+ * Converts an async throwing function into a Result-returning async function.
+ */
+export declare const tryCatchAsync: <T, E = unknown>(fn: () => Promise<T>, onError?: (error: unknown) => E) => Promise<Result<T, E>>;
+/**
+ * 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 declare const mapAsyncOption: <T, U>(opt: AsyncOption<T>, f: (value: T) => U | Promise<U>) => AsyncOption<U>;
+/**
+ * Maps a function over an async Result.
+ */
+export declare const mapAsyncResult: <T, U, E>(result: AsyncResult<T, E>, f: (value: T) => U | Promise<U>) => AsyncResult<U, E>;
+/**
+ * Converts an Option to a Result.
+ * None becomes Err with the provided error.
+ */
+export declare const optionToResult: <T, E>(opt: Option<T>, error: E) => Result<T, E>;
+/**
+ * Converts a Result to an Option.
+ * Err becomes None, discarding the error.
+ */
+export declare const resultToOption: <T, E>(result: Result<T, E>) => Option<T>;
+/**
+ * Combines multiple Options into an Option of an array.
+ * Returns None if any input is None.
+ */
+export declare const sequence: <T>(opts: Option<T>[]) => Option<T[]>;
+/**
+ * Combines multiple Results into a Result of an array.
+ * Returns the first Err encountered, or Ok with all values.
+ */
+export declare const sequenceResults: <T, E>(results: Result<T, E>[]) => Result<T[], E>;
+//# sourceMappingURL=effects.d.ts.map

package/dist/collections/core/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../../src/collections/core/effects.ts"],"names":[],"mappings":"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"}