dotdo 0.0.1 → 0.1.0

package/dist/workflows/context/experiment.js

@@ -0,0 +1,289 @@
+/**
+ * Experiment Context API for $.experiment()
+ *
+ * Provides a workflow context API for A/B testing experiments with support for:
+ * - $.experiment(id).allocate(userId) - Allocate user to variant
+ * - $.experiment(id).isEnabled() - Check if experiment is running
+ * - $.experiment(id).variant(name) - Get variant configuration
+ * - $.experiment(id).pause() / resume() / complete() - Lifecycle management
+ * - $.experiment(id).setTraffic(n) - Update traffic allocation
+ * - $.Experiment.create({...}) - Create new experiment
+ * - $.Experiment.list() - List all experiments
+ *
+ * @module workflows/context/experiment
+ */
+import { hashToInt } from '../hash';
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Maximum value for 32-bit hash (2^32 - 1)
+ */
+const MAX_HASH_VALUE = 0xffffffff;
+// ============================================================================
+// CORE ALLOCATION LOGIC
+// ============================================================================
+/**
+ * Check if user is in traffic allocation using deterministic hash
+ */
+function isInTraffic(experimentId, userId, traffic) {
+    if (traffic <= 0) {
+        return false;
+    }
+    if (traffic >= 1) {
+        return true;
+    }
+    const hashInput = `${userId}:${experimentId}:traffic`;
+    const hashValue = hashToInt(hashInput);
+    const normalizedHash = hashValue / MAX_HASH_VALUE;
+    return normalizedHash < traffic;
+}
+/**
+ * Assign user to a variant based on weighted distribution using deterministic hash
+ */
+function assignVariant(experimentId, userId, variants) {
+    if (!variants || variants.length === 0) {
+        return null;
+    }
+    // Calculate total weight
+    const totalWeight = variants.reduce((sum, variant) => sum + variant.weight, 0);
+    if (totalWeight === 0) {
+        return null;
+    }
+    // Use a different hash input for variant assignment
+    const hashInput = `${userId}:${experimentId}:variant`;
+    const hashValue = hashToInt(hashInput);
+    const normalizedHash = hashValue / MAX_HASH_VALUE;
+    const targetValue = normalizedHash * totalWeight;
+    // Find the variant based on cumulative weights
+    let cumulativeWeight = 0;
+    for (const variant of variants) {
+        cumulativeWeight += variant.weight;
+        if (targetValue < cumulativeWeight) {
+            return variant;
+        }
+    }
+    // Fallback to last variant (should not happen with proper weights)
+    return variants[variants.length - 1] ?? null;
+}
+/**
+ * Allocate a user to an experiment
+ *
+ * Allocation order:
+ * 1. Check experiment exists (non-existent = not in experiment)
+ * 2. Check experiment status (not running = not in experiment)
+ * 3. Check traffic allocation using deterministic hash
+ * 4. Assign to variant using weighted distribution
+ */
+export function allocateUser(experiment, userId) {
+    // Experiment doesn't exist
+    if (!experiment) {
+        return {
+            inExperiment: false,
+            variant: null,
+        };
+    }
+    // Check if experiment is running
+    if (experiment.status !== 'running') {
+        return {
+            inExperiment: false,
+            variant: null,
+        };
+    }
+    // Check traffic allocation
+    if (!isInTraffic(experiment.id, userId, experiment.traffic)) {
+        return {
+            inExperiment: false,
+            variant: null,
+        };
+    }
+    // Assign to variant
+    const variant = assignVariant(experiment.id, userId, experiment.variants);
+    if (variant) {
+        return {
+            inExperiment: true,
+            variant: variant.key,
+            payload: variant.payload,
+        };
+    }
+    // No variants assigned (shouldn't happen with valid experiment)
+    return {
+        inExperiment: true,
+        variant: null,
+    };
+}
+// ============================================================================
+// CONTEXT FACTORY
+// ============================================================================
+/**
+ * Creates an experiment context ($) with experiment support
+ *
+ * This factory creates a context object with:
+ * - $.experiment(id) - Returns an ExperimentInstance for per-experiment operations
+ * - $.Experiment - Collection-level operations (create, list)
+ * - $._storage - Internal storage for test setup
+ *
+ * @param existingStorage - Optional existing storage to reuse (for testing consistency)
+ * @returns An ExperimentContext object with experiment API methods
+ */
+export function createExperimentContext(existingStorage) {
+    // Internal experiment storage
+    const storage = existingStorage ?? {
+        experiments: new Map(),
+    };
+    /**
+     * Create an ExperimentInstance for a specific experiment ID
+     */
+    function createExperimentInstance(id) {
+        return {
+            /**
+             * Allocate a user to this experiment
+             * Uses deterministic hashing for consistent per-user assignment
+             */
+            async allocate(userId) {
+                const experiment = storage.experiments.get(id);
+                return allocateUser(experiment, userId);
+            },
+            /**
+             * Check if this experiment is enabled (running)
+             */
+            async isEnabled() {
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    return false;
+                }
+                return experiment.status === 'running';
+            },
+            /**
+             * Get a specific variant by name
+             */
+            async variant(name) {
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    return undefined;
+                }
+                return experiment.variants.find((v) => v.key === name);
+            },
+            /**
+             * Get the full experiment configuration
+             */
+            async get() {
+                return storage.experiments.get(id);
+            },
+            /**
+             * Pause the experiment
+             */
+            async pause() {
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    throw new Error(`Experiment '${id}' does not exist`);
+                }
+                experiment.status = 'paused';
+                experiment.updatedAt = new Date();
+                storage.experiments.set(id, experiment);
+            },
+            /**
+             * Resume a paused experiment
+             */
+            async resume() {
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    throw new Error(`Experiment '${id}' does not exist`);
+                }
+                experiment.status = 'running';
+                experiment.updatedAt = new Date();
+                storage.experiments.set(id, experiment);
+            },
+            /**
+             * Complete the experiment
+             */
+            async complete() {
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    throw new Error(`Experiment '${id}' does not exist`);
+                }
+                experiment.status = 'completed';
+                experiment.updatedAt = new Date();
+                storage.experiments.set(id, experiment);
+            },
+            /**
+             * Update traffic allocation
+             * @param traffic - Value between 0 and 1
+             */
+            async setTraffic(traffic) {
+                if (traffic < 0 || traffic > 1) {
+                    throw new Error(`Traffic must be between 0 and 1, got ${traffic}`);
+                }
+                const experiment = storage.experiments.get(id);
+                if (!experiment) {
+                    throw new Error(`Experiment '${id}' does not exist`);
+                }
+                experiment.traffic = traffic;
+                experiment.updatedAt = new Date();
+                storage.experiments.set(id, experiment);
+            },
+            /**
+             * Delete the experiment
+             */
+            async delete() {
+                storage.experiments.delete(id);
+            },
+        };
+    }
+    /**
+     * Experiment collection API
+     */
+    const experimentCollection = {
+        /**
+         * Create a new experiment
+         */
+        async create(options) {
+            // Validate experiment doesn't already exist
+            if (storage.experiments.has(options.id)) {
+                throw new Error(`Experiment '${options.id}' already exists`);
+            }
+            // Validate at least 2 variants
+            if (!options.variants || options.variants.length < 2) {
+                throw new Error('Experiment must have at least 2 variants');
+            }
+            // Validate all weights are positive
+            for (const variant of options.variants) {
+                if (variant.weight < 0) {
+                    throw new Error(`Variant weight must be non-negative, got ${variant.weight}`);
+                }
+            }
+            // Validate traffic
+            const traffic = options.traffic ?? 1.0;
+            if (traffic < 0 || traffic > 1) {
+                throw new Error(`Traffic must be between 0 and 1, got ${traffic}`);
+            }
+            const now = new Date();
+            const experiment = {
+                id: options.id,
+                traffic,
+                status: options.status ?? 'running',
+                variants: options.variants.map((v) => ({
+                    key: v.key,
+                    weight: v.weight,
+                    payload: v.payload,
+                })),
+                createdAt: now,
+                updatedAt: now,
+            };
+            storage.experiments.set(options.id, experiment);
+            return experiment;
+        },
+        /**
+         * List all experiments
+         */
+        async list() {
+            return Array.from(storage.experiments.values());
+        },
+    };
+    return {
+        experiment: createExperimentInstance,
+        Experiment: experimentCollection,
+        _storage: storage,
+    };
+}
+//# sourceMappingURL=experiment.js.map

package/dist/workflows/context/experiment.js.map

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

package/dist/workflows/context/flag.js

@@ -0,0 +1,244 @@
+/**
+ * Feature Flag Context API for $.flag() and $.flags
+ *
+ * Provides a workflow context API for feature flag evaluation with support for:
+ * - $.flag(id).isEnabled(userId) - Check if flag is enabled for user
+ * - $.flag(id).get(userId) - Get full evaluation result with variant/payload
+ * - $.flag(id).setTraffic(n) - Update traffic allocation
+ * - $.flag(id).enable() - Enable flag for all users
+ * - $.flag(id).disable() - Disable flag
+ * - $.flags.fetch() - Fetch all flags from storage
+ * - $.flags.evaluate(id, userId, flags) - Local evaluation without DB
+ *
+ * @module workflows/context/flag
+ */
+import { hashToInt } from '../hash';
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Maximum value for 32-bit hash (2^32 - 1)
+ */
+const MAX_HASH_VALUE = 0xffffffff;
+// ============================================================================
+// CORE EVALUATION LOGIC
+// ============================================================================
+/**
+ * Check if user is in traffic allocation using deterministic hash
+ */
+function isInTraffic(flagId, userId, traffic) {
+    if (traffic <= 0) {
+        return false;
+    }
+    if (traffic >= 1) {
+        return true;
+    }
+    const hashInput = `${userId}:${flagId}`;
+    const hashValue = hashToInt(hashInput);
+    const normalizedHash = hashValue / MAX_HASH_VALUE;
+    return normalizedHash < traffic;
+}
+/**
+ * Assign user to a branch based on weighted distribution using deterministic hash
+ */
+function assignBranch(flagId, userId, branches) {
+    if (!branches || branches.length === 0) {
+        return null;
+    }
+    // Calculate total weight
+    const totalWeight = branches.reduce((sum, branch) => sum + branch.weight, 0);
+    if (totalWeight === 0) {
+        return null;
+    }
+    // Use a different hash input for branch assignment to get independent randomization
+    const hashInput = `${userId}:${flagId}:branch`;
+    const hashValue = hashToInt(hashInput);
+    const normalizedHash = hashValue / MAX_HASH_VALUE;
+    const targetValue = normalizedHash * totalWeight;
+    // Find the branch based on cumulative weights
+    let cumulativeWeight = 0;
+    for (const branch of branches) {
+        cumulativeWeight += branch.weight;
+        if (targetValue < cumulativeWeight) {
+            return branch;
+        }
+    }
+    // Fallback to last branch (should not happen with proper weights)
+    return branches[branches.length - 1] ?? null;
+}
+/**
+ * Evaluate a flag for a given user
+ *
+ * Evaluation order:
+ * 1. Check flag exists (non-existent = disabled)
+ * 2. Check flag status (disabled = disabled)
+ * 3. Check traffic allocation using deterministic hash
+ * 4. Assign to branch using weighted distribution
+ *
+ * @param flag - The flag configuration (or undefined if not found)
+ * @param userId - The user ID for deterministic assignment
+ * @returns The evaluation result with enabled status, variant, and optional payload
+ */
+export function evaluateFlag(flag, userId) {
+    // Flag doesn't exist - return disabled
+    if (!flag) {
+        return {
+            enabled: false,
+            variant: null,
+        };
+    }
+    // Check if flag status is disabled
+    if (flag.status === 'disabled' || flag.status === 'archived') {
+        return {
+            enabled: false,
+            variant: null,
+        };
+    }
+    // Check traffic allocation
+    if (!isInTraffic(flag.id, userId, flag.traffic)) {
+        return {
+            enabled: false,
+            variant: null,
+        };
+    }
+    // Assign to branch
+    const branch = assignBranch(flag.id, userId, flag.branches);
+    if (branch) {
+        return {
+            enabled: true,
+            variant: branch.key,
+            payload: branch.payload,
+        };
+    }
+    // No branches - just enabled
+    return {
+        enabled: true,
+        variant: null,
+    };
+}
+// ============================================================================
+// CONTEXT FACTORY
+// ============================================================================
+/**
+ * Creates a mock workflow context ($) with flag support for testing
+ *
+ * This factory creates a context object with:
+ * - $.flag(id) - Returns a FlagContextInstance for per-flag operations
+ * - $.flags - Collection-level operations (fetch, evaluate)
+ * - $._storage - Internal storage for test setup
+ *
+ * @returns A FlagContext object with flag API methods
+ */
+export function createMockContext() {
+    // Internal flag storage
+    const storage = {
+        flags: new Map(),
+    };
+    /**
+     * Create a FlagContextInstance for a specific flag ID
+     */
+    function createFlagInstance(id) {
+        return {
+            /**
+             * Check if a user is enabled for this flag
+             * Uses deterministic hashing for consistent per-user assignment
+             */
+            async isEnabled(userId) {
+                const flag = storage.flags.get(id);
+                const result = evaluateFlag(flag, userId);
+                return result.enabled;
+            },
+            /**
+             * Get full evaluation result including variant and payload
+             */
+            async get(userId) {
+                const flag = storage.flags.get(id);
+                return evaluateFlag(flag, userId);
+            },
+            /**
+             * Update traffic allocation for this flag
+             * @param traffic - Value between 0 and 1
+             */
+            async setTraffic(traffic) {
+                // Validate traffic range
+                if (traffic < 0 || traffic > 1) {
+                    throw new Error(`Traffic must be between 0 and 1, got ${traffic}`);
+                }
+                const flag = storage.flags.get(id);
+                if (!flag) {
+                    throw new Error(`Flag '${id}' does not exist`);
+                }
+                flag.traffic = traffic;
+                flag.updatedAt = new Date();
+                storage.flags.set(id, flag);
+            },
+            /**
+             * Enable the flag for all users
+             * Sets traffic to 1.0 and status to active
+             */
+            async enable() {
+                const flag = storage.flags.get(id);
+                if (!flag) {
+                    throw new Error(`Flag '${id}' does not exist`);
+                }
+                flag.traffic = 1.0;
+                flag.status = 'active';
+                flag.updatedAt = new Date();
+                storage.flags.set(id, flag);
+            },
+            /**
+             * Disable the flag for all users
+             * Sets status to disabled but preserves traffic value
+             */
+            async disable() {
+                const flag = storage.flags.get(id);
+                if (!flag) {
+                    throw new Error(`Flag '${id}' does not exist`);
+                }
+                flag.status = 'disabled';
+                flag.updatedAt = new Date();
+                storage.flags.set(id, flag);
+            },
+        };
+    }
+    /**
+     * Flags collection API
+     */
+    const flagsCollection = {
+        /**
+         * Fetch all flags from storage
+         * Returns a deep copy to prevent mutations
+         */
+        async fetch() {
+            const result = {};
+            for (const [key, flag] of storage.flags.entries()) {
+                // Create a deep copy to prevent mutations affecting storage
+                result[key] = {
+                    ...flag,
+                    branches: flag.branches.map((b) => ({ ...b })),
+                    createdAt: new Date(flag.createdAt.getTime()),
+                    updatedAt: new Date(flag.updatedAt.getTime()),
+                };
+            }
+            return result;
+        },
+        /**
+         * Evaluate a flag locally against provided flags object
+         * This is synchronous and doesn't hit storage
+         *
+         * @param flagId - The flag ID to evaluate
+         * @param userId - The user ID for deterministic assignment
+         * @param flags - The flags object to evaluate against
+         */
+        evaluate(flagId, userId, flags) {
+            const flag = flags[flagId];
+            return evaluateFlag(flag, userId);
+        },
+    };
+    return {
+        flag: createFlagInstance,
+        flags: flagsCollection,
+        _storage: storage,
+    };
+}
+//# sourceMappingURL=flag.js.map

package/dist/workflows/context/flag.js.map

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