@procedures/collections 0.47.1 → 0.47.2

package/src/core/policies.ts

@@ -1,316 +0,0 @@
-/**
- * Policy types for configurable collection behaviors.
- *
- * Policies define how collections handle edge cases like overflow,
- * underflow, and eviction. These are used by behavior decorators
- * to provide flexible, composable behavior.
- */
-
-// ============================================================================
-// Overflow Policies - what to do when a bounded collection is full
-// ============================================================================
-
-/**
- * Policy for handling overflow when adding to a full bounded collection.
- *
- * - 'throw': Throw an error when attempting to add to a full collection
- * - 'drop-oldest': Remove the oldest element and add the new one
- * - 'drop-newest': Ignore the new element (don't add it)
- * - 'reject': Return false/None but don't throw (graceful failure)
- * - 'grow': Automatically increase capacity (becomes unbounded)
- * - 'block': For async collections, wait until space is available
- */
-export type OverflowPolicy =
-  | "throw"
-  | "drop-oldest"
-  | "drop-newest"
-  | "reject"
-  | "grow"
-  | "block";
-
-/**
- * Context information provided when overflow occurs.
- */
-export interface OverflowContext<T> {
-  /** The element that triggered the overflow. */
-  readonly newElement: T;
-  /** Current size of the collection. */
-  readonly currentSize: number;
-  /** Maximum capacity of the collection. */
-  readonly capacity: number;
-  /** Timestamp when overflow occurred. */
-  readonly timestamp: number;
-}
-
-/**
- * Callback invoked when overflow occurs.
- * Can be used for logging, metrics, or custom handling.
- */
-export type OverflowHandler<T> = (context: OverflowContext<T>) => void;
-
-// ============================================================================
-// Underflow Policies - what to do when removing from an empty collection
-// ============================================================================
-
-/**
- * Policy for handling underflow when removing from an empty collection.
- *
- * - 'throw': Throw an error when attempting to remove from empty collection
- * - 'return-none': Return None/undefined (graceful failure)
- * - 'return-default': Return a default value provided by user
- * - 'block': For async collections, wait until an element is available
- */
-export type UnderflowPolicy =
-  | "throw"
-  | "return-none"
-  | "return-default"
-  | "block";
-
-/**
- * Context information provided when underflow occurs.
- */
-export interface UnderflowContext {
-  /** The operation that triggered the underflow. */
-  readonly operation: string;
-  /** Timestamp when underflow occurred. */
-  readonly timestamp: number;
-}
-
-/**
- * Callback invoked when underflow occurs.
- */
-export type UnderflowHandler = (context: UnderflowContext) => void;
-
-// ============================================================================
-// Eviction Policies - how to choose which element to remove
-// ============================================================================
-
-/**
- * Policy for choosing which element to evict from a bounded collection.
- *
- * - 'lru': Least Recently Used - evict element not accessed for longest time
- * - 'lfu': Least Frequently Used - evict element accessed least often
- * - 'fifo': First In First Out - evict oldest inserted element
- * - 'lifo': Last In First Out - evict newest inserted element (stack-like)
- * - 'random': Evict a random element
- * - 'ttl': Time To Live - evict elements that have expired
- * - 'priority': Evict element with lowest priority
- * - 'custom': User-provided eviction function
- */
-export type EvictionPolicy =
-  | "lru"
-  | "lfu"
-  | "fifo"
-  | "lifo"
-  | "random"
-  | "ttl"
-  | "priority"
-  | "custom";
-
-/**
- * Metadata tracked for eviction decisions.
- */
-export interface EvictionMetadata {
-  /** When the element was inserted. */
-  readonly insertedAt: number;
-  /** When the element was last accessed. */
-  lastAccessedAt: number;
-  /** How many times the element has been accessed. */
-  accessCount: number;
-  /** Time-to-live expiration timestamp (if applicable). */
-  readonly expiresAt?: number;
-  /** Priority value (higher = more important, if applicable). */
-  readonly priority?: number;
-}
-
-/**
- * Information about an element that can be evicted.
- */
-export interface EvictionCandidate<T> {
-  /** The element value. */
-  readonly element: T;
-  /** Eviction metadata for this element. */
-  readonly metadata: EvictionMetadata;
-}
-
-/**
- * Custom eviction function.
- * Given candidates, returns the element to evict.
- */
-export type EvictionSelector<T> = (
-  candidates: EvictionCandidate<T>[]
-) => T | undefined;
-
-// ============================================================================
-// Retry Policies - for async operations
-// ============================================================================
-
-/**
- * Policy for retrying failed async operations.
- */
-export interface RetryPolicy {
-  /** Maximum number of retry attempts. */
-  readonly maxAttempts: number;
-  /** Initial delay in milliseconds. */
-  readonly initialDelay: number;
-  /** Backoff strategy. */
-  readonly backoff: "none" | "linear" | "exponential";
-  /** Maximum delay cap (for backoff). */
-  readonly maxDelay?: number;
-  /** Jitter to add randomness and avoid thundering herd. */
-  readonly jitter?: boolean;
-}
-
-/**
- * Context for retry decisions.
- */
-export interface RetryContext {
-  /** Current attempt number (1-indexed). */
-  readonly attempt: number;
-  /** The error that caused the retry. */
-  readonly error: unknown;
-  /** Elapsed time since first attempt. */
-  readonly elapsedMs: number;
-}
-
-/**
- * Callback to determine if an error is retryable.
- */
-export type RetryPredicate = (context: RetryContext) => boolean;
-
-// ============================================================================
-// Conflict Resolution Policies - for concurrent modifications
-// ============================================================================
-
-/**
- * Policy for resolving conflicts when same key is modified concurrently.
- *
- * - 'last-write-wins': Most recent write takes precedence
- * - 'first-write-wins': First write takes precedence
- * - 'merge': Call merge function to combine values
- * - 'throw': Throw an error on conflict
- */
-export type ConflictResolutionPolicy =
-  | "last-write-wins"
-  | "first-write-wins"
-  | "merge"
-  | "throw";
-
-/**
- * Function to merge conflicting values.
- */
-export type MergeFunction<T> = (current: T, incoming: T) => T;
-
-// ============================================================================
-// Compaction Policies - for memory management
-// ============================================================================
-
-/**
- * Policy for when to compact internal storage.
- */
-export interface CompactionPolicy {
-  /** Compact when capacity utilization drops below this ratio (0-1). */
-  readonly minLoadFactor?: number;
-  /** Compact when wasted space exceeds this many elements. */
-  readonly maxWastedSpace?: number;
-  /** Automatically compact on every removal. */
-  readonly autoCompact?: boolean;
-}
-
-// ============================================================================
-// Growth Policies - for dynamic capacity
-// ============================================================================
-
-/**
- * Policy for how to grow capacity when needed.
- */
-export interface GrowthPolicy {
-  /** Growth strategy. */
-  readonly strategy: "double" | "linear" | "golden-ratio" | "custom";
-  /** For linear growth, how many elements to add. */
-  readonly linearIncrement?: number;
-  /** For custom growth, a function to calculate new capacity. */
-  readonly customGrowth?: (currentCapacity: number) => number;
-  /** Maximum capacity limit (prevent unbounded growth). */
-  readonly maxCapacity?: number;
-}
-
-// ============================================================================
-// Validation Policies - for type checking
-// ============================================================================
-
-/**
- * Validation action when an invalid element is encountered.
- *
- * - 'throw': Throw an error
- * - 'drop': Silently drop the invalid element
- * - 'coerce': Attempt to coerce to valid type
- * - 'log': Log warning but allow
- */
-export type ValidationPolicy = "throw" | "drop" | "coerce" | "log";
-
-/**
- * Context for validation failures.
- */
-export interface ValidationContext<T> {
-  /** The invalid element. */
-  readonly element: T;
-  /** Validation error message/details. */
-  readonly error: unknown;
-  /** The operation that triggered validation. */
-  readonly operation: string;
-}
-
-/**
- * Callback invoked on validation failures.
- */
-export type ValidationHandler<T> = (context: ValidationContext<T>) => void;
-
-// ============================================================================
-// Default policies
-// ============================================================================
-
-/**
- * Default overflow policy: throw an error.
- */
-export const DEFAULT_OVERFLOW_POLICY: OverflowPolicy = "throw";
-
-/**
- * Default underflow policy: throw an error.
- */
-export const DEFAULT_UNDERFLOW_POLICY: UnderflowPolicy = "throw";
-
-/**
- * Default eviction policy: FIFO (oldest first).
- */
-export const DEFAULT_EVICTION_POLICY: EvictionPolicy = "fifo";
-
-/**
- * Default retry policy: 3 attempts with exponential backoff.
- */
-export const DEFAULT_RETRY_POLICY: RetryPolicy = {
-  maxAttempts: 3,
-  initialDelay: 100,
-  backoff: "exponential",
-  maxDelay: 5000,
-  jitter: true,
-};
-
-/**
- * Default conflict resolution: last write wins.
- */
-export const DEFAULT_CONFLICT_POLICY: ConflictResolutionPolicy =
-  "last-write-wins";
-
-/**
- * Default growth policy: double capacity.
- */
-export const DEFAULT_GROWTH_POLICY: GrowthPolicy = {
-  strategy: "double",
-  maxCapacity: Number.MAX_SAFE_INTEGER,
-};
-
-/**
- * Default validation policy: throw on invalid.
- */
-export const DEFAULT_VALIDATION_POLICY: ValidationPolicy = "throw";

package/src/core/traits.ts

@@ -1,164 +0,0 @@
-/**
- * Core traits and capability interfaces for the collections framework.
- *
- * These traits define fundamental capabilities that collections can have,
- * following the Interface Segregation Principle (SOLID).
- */
-
-/**
- * Equality comparison function.
- * Returns true if two values are considered equal.
- *
- * @example
- * const primitiveEq: Eq<number> = (a, b) => a === b
- * const objectEq: Eq<Person> = (a, b) => a.id === b.id
- */
-export type Eq<T> = (a: T, b: T) => boolean;
-
-/**
- * Hash function for creating hash codes.
- * Returns a 32-bit integer hash of the value.
- *
- * Must satisfy: if eq(a, b) === true, then hash(a) === hash(b)
- *
- * @example
- * const stringHash: Hash<string> = (s) => {
- *   let h = 0;
- *   for (let i = 0; i < s.length; i++) {
- *     h = ((h << 5) - h) + s.charCodeAt(i);
- *     h = h & h; // Convert to 32-bit integer
- *   }
- *   return h;
- * }
- */
-export type Hash<T> = (value: T) => number;
-
-/**
- * Comparison function for ordering values.
- * Returns:
- * - negative number if a < b
- * - zero if a === b
- * - positive number if a > b
- *
- * Must be transitive and consistent with equality.
- *
- * @example
- * const numberCompare: Compare<number> = (a, b) => a - b
- * const reverseCompare = <T>(cmp: Compare<T>): Compare<T> => (a, b) => cmp(b, a)
- */
-export type Compare<T> = (a: T, b: T) => number;
-
-/**
- * Capability: Has a size property.
- */
-export interface Sized {
-  /** The number of elements in the collection. */
-  readonly size: number;
-}
-
-/**
- * Capability: Can be cleared (all elements removed).
- */
-export interface Clearable {
-  /** Removes all elements from the collection. */
-  clear(): void;
-}
-
-/**
- * Capability: Can check if empty.
- */
-export interface Emptiable {
-  /** Returns true if the collection contains no elements. */
-  readonly isEmpty: boolean;
-}
-
-/**
- * Capability: Can be cloned.
- */
-export interface Cloneable<T> {
-  /** Creates a shallow copy of the collection. */
-  clone(): T;
-}
-
-/**
- * Capability: Can be converted to an array.
- */
-export interface ArrayConvertible<T> {
-  /** Returns an array containing all elements in the collection. */
-  toArray(): T[];
-}
-
-/**
- * Base read-only collection capabilities.
- * Combines common traits that most collections share.
- */
-export interface ReadonlyCollectionBase<T>
-  extends Sized,
-    Emptiable,
-    Iterable<T>,
-    ArrayConvertible<T> {}
-
-/**
- * Base mutable collection capabilities.
- * Adds mutation operations to readonly base.
- */
-export interface MutableCollectionBase<T>
-  extends ReadonlyCollectionBase<T>,
-    Clearable {}
-
-/**
- * Equality provider - allows collections to specify custom equality.
- */
-export interface EqualityProvider<T> {
-  /** The equality function used by this collection. */
-  readonly eq: Eq<T>;
-}
-
-/**
- * Hash provider - allows collections to specify custom hashing.
- */
-export interface HashProvider<T> {
-  /** The hash function used by this collection. */
-  readonly hash: Hash<T>;
-}
-
-/**
- * Comparison provider - allows collections to specify custom ordering.
- */
-export interface ComparisonProvider<T> {
-  /** The comparison function used by this collection. */
-  readonly compare: Compare<T>;
-}
-
-/**
- * Bounded collection - has a maximum capacity.
- */
-export interface Bounded {
-  /** The maximum number of elements this collection can hold. */
-  readonly capacity: number;
-
-  /** Returns true if the collection is at capacity. */
-  readonly isFull: boolean;
-
-  /** Returns the number of additional elements that can be added. */
-  readonly remainingCapacity: number;
-}
-
-/**
- * Disposable resource - can be explicitly cleaned up.
- */
-export interface Disposable {
-  /** Releases any resources held by this collection. */
-  dispose(): void;
-}
-
-/**
- * Freezable collection - can be made immutable.
- */
-export interface Freezable<T> {
-  /** Makes this collection immutable. Returns self for chaining. */
-  freeze(): T;
-
-  /** Returns true if this collection is frozen. */
-  readonly isFrozen: boolean;
-}