@portel/photon-core 2.8.4 → 2.9.1

package/src/schema-extractor.ts

@@ -11,6 +11,8 @@
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
 import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam } from './types.js';
+import { parseDuration, parseRate } from './utils/duration.js';
+import { builtinRegistry, type MiddlewareDeclaration } from './middleware.js';
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -106,6 +108,11 @@ export class SchemaExtractor {
 
         const jsdoc = this.getJSDocComment(member, sourceFile);
 
+        // Skip @internal methods — hidden from LLM and sidebar
+        if (/@internal\b/.test(jsdoc)) {
+          return;
+        }
+
         // Check if this is an async generator method (has asterisk token)
         const isGenerator = member.asteriskToken !== undefined;
 
@@ -182,6 +189,22 @@ export class SchemaExtractor {
           const scheduled = this.extractScheduled(jsdoc, methodName);
           const locked = this.extractLocked(jsdoc, methodName);
 
+          // Functional tags — individual fields kept for backward compat
+          const fallback = this.extractFallback(jsdoc);
+          const logged = this.extractLogged(jsdoc);
+          const circuitBreaker = this.extractCircuitBreaker(jsdoc);
+          const cached = this.extractCached(jsdoc);
+          const timeout = this.extractTimeout(jsdoc);
+          const retryable = this.extractRetryable(jsdoc);
+          const throttled = this.extractThrottled(jsdoc);
+          const debounced = this.extractDebounced(jsdoc);
+          const queued = this.extractQueued(jsdoc);
+          const validations = this.extractValidations(jsdoc);
+          const deprecated = this.extractDeprecated(jsdoc);
+
+          // Build unified middleware declarations (single source of truth for runtime)
+          const middleware = this.buildMiddlewareDeclarations(jsdoc);
+
           // Check for static keyword on the method
           const isStaticMethod = member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) || false;
 
@@ -204,6 +227,20 @@ export class SchemaExtractor {
             ...(webhook !== undefined ? { webhook } : {}),
             ...(scheduled ? { scheduled } : {}),
             ...(locked !== undefined ? { locked } : {}),
+            // Functional tags (individual fields for backward compat)
+            ...(fallback ? { fallback } : {}),
+            ...(logged ? { logged } : {}),
+            ...(circuitBreaker ? { circuitBreaker } : {}),
+            ...(cached ? { cached } : {}),
+            ...(timeout ? { timeout } : {}),
+            ...(retryable ? { retryable } : {}),
+            ...(throttled ? { throttled } : {}),
+            ...(debounced ? { debounced } : {}),
+            ...(queued ? { queued } : {}),
+            ...(validations && validations.length > 0 ? { validations } : {}),
+            ...(deprecated !== undefined ? { deprecated } : {}),
+            // Unified middleware declarations (new — runtime uses this)
+            ...(middleware.length > 0 ? { middleware } : {}),
           });
         }
       };
@@ -712,13 +749,159 @@ export class SchemaExtractor {
     return initializer.getText(sourceFile);
   }
 
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // INLINE CONFIG + @use PARSING
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Parse inline {@prop value} config from a string
+   * @example parseInlineConfig('{@ttl 5m} {@key params.userId}')
+   *   → { ttl: '5m', key: 'params.userId' }
+   */
+  parseInlineConfig(text: string): Record<string, string> {
+    const config: Record<string, string> = {};
+    const regex = /\{@(\w+)\s+([^}]+)\}/g;
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+      config[match[1]] = match[2].trim();
+    }
+    return config;
+  }
+
+  /**
+   * Extract @use declarations from JSDoc
+   * @example extractUseDeclarations('* @use audit {@level info} {@tags api}')
+   *   → [{ name: 'audit', rawConfig: { level: 'info', tags: 'api' } }]
+   */
+  extractUseDeclarations(jsdocContent: string): Array<{ name: string; rawConfig: Record<string, string> }> {
+    const declarations: Array<{ name: string; rawConfig: Record<string, string> }> = [];
+    const regex = /@use\s+([\w][\w-]*)((?:\s+\{@\w+\s+[^}]+\})*)/g;
+    let match;
+    while ((match = regex.exec(jsdocContent)) !== null) {
+      const name = match[1];
+      const configStr = match[2] || '';
+      const rawConfig = this.parseInlineConfig(configStr);
+      declarations.push({ name, rawConfig });
+    }
+    return declarations;
+  }
+
+  /**
+   * Build middleware declarations from all tags on a method's JSDoc.
+   * Converts both sugar tags (@cached 5m) and @use tags into a unified
+   * MiddlewareDeclaration[] array.
+   */
+  buildMiddlewareDeclarations(jsdocContent: string): MiddlewareDeclaration[] {
+    const declarations: MiddlewareDeclaration[] = [];
+
+    // 1. Extract sugar tags → convert to declarations
+
+    // @fallback
+    const fallback = this.extractFallback(jsdocContent);
+    if (fallback) {
+      const def = builtinRegistry.get('fallback');
+      declarations.push({ name: 'fallback', config: fallback, phase: def?.phase ?? 3 });
+    }
+
+    // @logged
+    const logged = this.extractLogged(jsdocContent);
+    if (logged) {
+      const def = builtinRegistry.get('logged');
+      declarations.push({ name: 'logged', config: logged, phase: def?.phase ?? 5 });
+    }
+
+    // @circuitBreaker
+    const circuitBreaker = this.extractCircuitBreaker(jsdocContent);
+    if (circuitBreaker) {
+      const def = builtinRegistry.get('circuitBreaker');
+      declarations.push({ name: 'circuitBreaker', config: circuitBreaker, phase: def?.phase ?? 8 });
+    }
+
+    // @cached
+    const cached = this.extractCached(jsdocContent);
+    if (cached) {
+      const def = builtinRegistry.get('cached');
+      declarations.push({ name: 'cached', config: cached, phase: def?.phase ?? 30 });
+    }
+
+    // @timeout
+    const timeout = this.extractTimeout(jsdocContent);
+    if (timeout) {
+      const def = builtinRegistry.get('timeout');
+      declarations.push({ name: 'timeout', config: timeout, phase: def?.phase ?? 70 });
+    }
+
+    // @retryable
+    const retryable = this.extractRetryable(jsdocContent);
+    if (retryable) {
+      const def = builtinRegistry.get('retryable');
+      declarations.push({ name: 'retryable', config: retryable, phase: def?.phase ?? 80 });
+    }
+
+    // @throttled
+    const throttled = this.extractThrottled(jsdocContent);
+    if (throttled) {
+      const def = builtinRegistry.get('throttled');
+      declarations.push({ name: 'throttled', config: throttled, phase: def?.phase ?? 10 });
+    }
+
+    // @debounced
+    const debounced = this.extractDebounced(jsdocContent);
+    if (debounced) {
+      const def = builtinRegistry.get('debounced');
+      declarations.push({ name: 'debounced', config: debounced, phase: def?.phase ?? 20 });
+    }
+
+    // @queued
+    const queued = this.extractQueued(jsdocContent);
+    if (queued) {
+      const def = builtinRegistry.get('queued');
+      declarations.push({ name: 'queued', config: queued, phase: def?.phase ?? 50 });
+    }
+
+    // @validate
+    const validations = this.extractValidations(jsdocContent);
+    if (validations && validations.length > 0) {
+      const def = builtinRegistry.get('validate');
+      declarations.push({ name: 'validate', config: { validations }, phase: def?.phase ?? 40 });
+    }
+
+    // @locked (handled as middleware when it appears as a functional tag)
+    const lockedMatch = jsdocContent.match(/@locked(?:\s+(\w[\w\-:]*))?/i);
+    if (lockedMatch) {
+      const lockName = lockedMatch[1]?.trim() || '';
+      const def = builtinRegistry.get('locked');
+      declarations.push({ name: 'locked', config: { name: lockName }, phase: def?.phase ?? 60 });
+    }
+
+    // 2. Extract @use declarations
+    const useDecls = this.extractUseDeclarations(jsdocContent);
+    for (const { name, rawConfig } of useDecls) {
+      // Check if this is a built-in (allow @use cached {@ttl 5m} syntax)
+      const def = builtinRegistry.get(name);
+      if (def) {
+        // Use parseConfig if available, otherwise pass raw
+        const config = def.parseConfig ? def.parseConfig(rawConfig) : rawConfig;
+        // Don't duplicate if sugar tag already added this middleware
+        if (!declarations.some(d => d.name === name)) {
+          declarations.push({ name, config, phase: def.phase ?? 45 });
+        }
+      } else {
+        // Custom middleware — phase defaults to 45
+        declarations.push({ name, config: rawConfig, phase: 45 });
+      }
+    }
+
+    return declarations;
+  }
+
   /**
    * Extract main description from JSDoc comment
    */
   private extractDescription(jsdocContent: string): string {
     // Split by @tags that appear at start of a JSDoc line (after optional * prefix)
     // This avoids matching @tag references inline in description text
-    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
+    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
 
     // Remove leading * from each line and trim
     const lines = beforeTags
@@ -1237,6 +1420,153 @@ export class SchemaExtractor {
     return undefined;
   }
 
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // FUNCTIONAL TAG EXTRACTION
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Extract logging config from @logged tag
+   * - @logged → info level
+   * - @logged debug → debug level
+   */
+  private extractLogged(jsdocContent: string): { level: string } | undefined {
+    const match = jsdocContent.match(/@logged(?:\s+(\w+))?/i);
+    if (!match) return undefined;
+    return { level: match[1]?.trim() || 'info' };
+  }
+
+  /**
+   * Extract fallback value from @fallback tag
+   * - @fallback [] → empty array on error
+   * - @fallback {} → empty object on error
+   * - @fallback null → null on error
+   * - @fallback 0 → zero on error
+   */
+  private extractFallback(jsdocContent: string): { value: string } | undefined {
+    const match = jsdocContent.match(/@fallback\s+(.+?)(?:\s*$|\s*\n|\s*\*)/m);
+    if (!match) return undefined;
+    return { value: match[1].trim() };
+  }
+
+  /**
+   * Extract circuit breaker configuration from @circuitBreaker tag
+   * - @circuitBreaker 5 30s → 5 failures, 30s reset
+   * - @circuitBreaker 3 1m → 3 failures, 1 minute reset
+   */
+  private extractCircuitBreaker(jsdocContent: string): { threshold: number; resetAfter: string } | undefined {
+    const match = jsdocContent.match(/@circuitBreaker\s+(\d+)\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day))/i);
+    if (!match) return undefined;
+    return { threshold: parseInt(match[1], 10), resetAfter: match[2] };
+  }
+
+  /**
+   * Extract cache configuration from @cached tag
+   * - @cached → default 5m TTL
+   * - @cached 30s → 30 second TTL
+   * - @cached 1h → 1 hour TTL
+   */
+  private extractCached(jsdocContent: string): { ttl: number } | undefined {
+    const match = jsdocContent.match(/@cached(?:\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
+    if (!match) return undefined;
+    const ttl = match[1] ? parseDuration(match[1]) : 300_000; // default 5m
+    return { ttl };
+  }
+
+  /**
+   * Extract timeout configuration from @timeout tag
+   * - @timeout 30s → 30 second timeout
+   * - @timeout 5m → 5 minute timeout
+   */
+  private extractTimeout(jsdocContent: string): { ms: number } | undefined {
+    const match = jsdocContent.match(/@timeout\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day))/i);
+    if (!match) return undefined;
+    return { ms: parseDuration(match[1]) };
+  }
+
+  /**
+   * Extract retry configuration from @retryable tag
+   * - @retryable → default 3 retries, 1s delay
+   * - @retryable 5 → 5 retries, 1s delay
+   * - @retryable 3 2s → 3 retries, 2s delay
+   */
+  private extractRetryable(jsdocContent: string): { count: number; delay: number } | undefined {
+    const match = jsdocContent.match(/@retryable(?:\s+(\d+))?(?:\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
+    if (!match) return undefined;
+    const count = match[1] ? parseInt(match[1], 10) : 3;
+    const delay = match[2] ? parseDuration(match[2]) : 1_000;
+    return { count, delay };
+  }
+
+  /**
+   * Extract throttle configuration from @throttled tag
+   * - @throttled 10/min → 10 calls per minute
+   * - @throttled 100/h → 100 calls per hour
+   */
+  private extractThrottled(jsdocContent: string): { count: number; windowMs: number } | undefined {
+    const match = jsdocContent.match(/@throttled\s+(\d+\/(?:s|sec|m|min|h|hr|d|day))/i);
+    if (!match) return undefined;
+    return parseRate(match[1]);
+  }
+
+  /**
+   * Extract debounce configuration from @debounced tag
+   * - @debounced → default 500ms
+   * - @debounced 200ms → 200ms delay
+   * - @debounced 1s → 1 second delay
+   */
+  private extractDebounced(jsdocContent: string): { delay: number } | undefined {
+    const match = jsdocContent.match(/@debounced(?:\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
+    if (!match) return undefined;
+    const delay = match[1] ? parseDuration(match[1]) : 500;
+    return { delay };
+  }
+
+  /**
+   * Extract queue configuration from @queued tag
+   * - @queued → default concurrency 1
+   * - @queued 3 → concurrency 3
+   */
+  private extractQueued(jsdocContent: string): { concurrency: number } | undefined {
+    const match = jsdocContent.match(/@queued(?:\s+(\d+))?/i);
+    if (!match) return undefined;
+    const concurrency = match[1] ? parseInt(match[1], 10) : 1;
+    return { concurrency };
+  }
+
+  /**
+   * Extract validation rules from @validate tags
+   * - @validate params.email must be a valid email
+   * - @validate params.amount must be positive
+   */
+  private extractValidations(jsdocContent: string): Array<{ field: string; rule: string }> | undefined {
+    const validations: Array<{ field: string; rule: string }> = [];
+    const regex = /@validate\s+([\w.]+)\s+(.+)/g;
+    let match;
+    while ((match = regex.exec(jsdocContent)) !== null) {
+      validations.push({
+        field: match[1].replace(/^params\./, ''), // strip params. prefix
+        rule: match[2].trim().replace(/\*\/$/, '').trim(), // strip JSDoc closing
+      });
+    }
+    return validations.length > 0 ? validations : undefined;
+  }
+
+  /**
+   * Extract deprecation notice from @deprecated tag (class-level, not param-level)
+   * - @deprecated → true
+   * - @deprecated Use addV2 instead → "Use addV2 instead"
+   *
+   * Note: Only matches @deprecated at the start of a JSDoc line (after * prefix),
+   * NOT inside {@deprecated} inline tags (those are param-level).
+   */
+  private extractDeprecated(jsdocContent: string): string | true | undefined {
+    // Match @deprecated at start of line (with optional * prefix), not inside {}
+    const match = jsdocContent.match(/(?:^|\n)\s*\*?\s*@deprecated(?:\s+([^\n*]+))?/i);
+    if (!match) return undefined;
+    const message = match[1]?.trim();
+    return message || true;
+  }
+
   /**
    * Extract URI pattern from @Static tag
    * Example: @Static github://repos/{owner}/{repo}/readme
@@ -1663,7 +1993,7 @@ export class SchemaExtractor {
    *  * @prompt system ./prompts/system.md
    *  * @resource config ./resources/config.json
    *  *\/
-   * export default class MyPhoton extends PhotonMCP { ... }
+   * export default class MyPhoton extends Photon { ... }
    * ```
    */
   extractAssets(source: string, assetFolder?: string): PhotonAssets {
@@ -1828,3 +2158,29 @@ export class SchemaExtractor {
     return mimeTypes[ext] || 'application/octet-stream';
   }
 }
+
+/**
+ * Capability types that can be auto-detected from source code
+ */
+export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances';
+
+/**
+ * Detect capabilities used by a Photon from its source code.
+ *
+ * Scans for `this.emit(`, `this.memory`, `this.call(`, etc. patterns
+ * and returns the set of capabilities that the runtime should inject.
+ *
+ * This enables plain classes (no extends Photon) to use all framework
+ * features — the loader detects usage and injects automatically.
+ */
+export function detectCapabilities(source: string): Set<PhotonCapability> {
+  const caps = new Set<PhotonCapability>();
+  if (/this\.emit\s*\(/.test(source)) caps.add('emit');
+  if (/this\.memory\b/.test(source)) caps.add('memory');
+  if (/this\.call\s*\(/.test(source)) caps.add('call');
+  if (/this\.mcp\s*\(/.test(source)) caps.add('mcp');
+  if (/this\.withLock\s*\(/.test(source)) caps.add('lock');
+  if (/this\.instanceMeta\b/.test(source)) caps.add('instanceMeta');
+  if (/this\.allInstances\s*\(/.test(source)) caps.add('allInstances');
+  return caps;
+}

package/src/stateful.ts

@@ -690,6 +690,8 @@ export interface MaybeStatefulResult<T> {
   result?: T;
   /** Error message (if failed) */
   error?: string;
+  /** Original error object (preserves .name for typed errors like PhotonTimeoutError) */
+  originalError?: Error;
   /** Run ID (only if stateful - checkpoint was yielded) */
   runId?: string;
   /** Was this a stateful workflow? */
@@ -821,6 +823,7 @@ export async function maybeStatefulExecute<T>(
     } catch (error: any) {
       return {
         error: error.message,
+        originalError: error instanceof Error ? error : undefined,
         isStateful: false,
         resumed: false,
         checkpointsCompleted: 0,
@@ -947,6 +950,7 @@ export async function maybeStatefulExecute<T>(
 
     return {
       error: error.message,
+      originalError: error instanceof Error ? error : undefined,
       runId,
       isStateful,
       resumed: false,

package/src/types.ts

@@ -96,9 +96,104 @@ export interface ExtractedSchema {
    * - string: custom lock name (e.g., @locked board:write)
    */
   locked?: boolean | string;
+
+  // ═══ FUNCTIONAL TAGS ═══
+
+  /**
+   * Logging configuration (from @logged tag)
+   * Auto-logs method execution with timing and error details
+   * @example @logged or @logged debug
+   */
+  logged?: { level: string };
+
+  /**
+   * Fallback value on error (from @fallback tag)
+   * Returns this value instead of throwing when the method fails
+   * @example @fallback []
+   */
+  fallback?: { value: string };
+
+  /**
+   * Circuit breaker configuration (from @circuitBreaker tag)
+   * Fast-rejects after N consecutive failures, probes after reset period
+   * @example @circuitBreaker 5 30s
+   */
+  circuitBreaker?: { threshold: number; resetAfter: string };
+
+  /**
+   * Cache configuration (from @cached tag)
+   * Memoize return value for the specified TTL
+   * @example @cached 5m
+   */
+  cached?: { ttl: number };
+
+  /**
+   * Execution timeout in ms (from @timeout tag)
+   * Rejects with TimeoutError if method doesn't resolve in time
+   * @example @timeout 30s
+   */
+  timeout?: { ms: number };
+
+  /**
+   * Auto-retry configuration (from @retryable tag)
+   * Retries on failure with delay between attempts
+   * @example @retryable 3 1s
+   */
+  retryable?: { count: number; delay: number };
+
+  /**
+   * Rate limiting configuration (from @throttled tag)
+   * At most N calls per time window
+   * @example @throttled 10/min
+   */
+  throttled?: { count: number; windowMs: number };
+
+  /**
+   * Debounce configuration (from @debounced tag)
+   * Collapses rapid repeated calls — only the last one executes
+   * @example @debounced 500ms
+   */
+  debounced?: { delay: number };
+
+  /**
+   * Queue configuration (from @queued tag)
+   * At most N concurrent executions, excess calls are queued
+   * @example @queued 1
+   */
+  queued?: { concurrency: number };
+
+  /**
+   * Custom validation rules (from @validate tag)
+   * Runtime validation beyond JSON Schema
+   * @example @validate params.email must be a valid email
+   */
+  validations?: Array<{ field: string; rule: string }>;
+
+  /**
+   * Deprecation notice (from @deprecated tag)
+   * Tool still works but shows warnings everywhere
+   * @example @deprecated Use addV2 instead
+   */
+  deprecated?: string | true;
+
+  // ═══ MIDDLEWARE PIPELINE ═══
+
+  /**
+   * Unified middleware declarations (from @use tags and sugar tags)
+   * Single source of truth for the runtime middleware pipeline.
+   * Replaces individual functional tag fields for execution purposes.
+   */
+  middleware?: Array<{
+    name: string;
+    config: Record<string, any>;
+    phase: number;
+  }>;
+
+  /** When true, method uses individual params instead of a single params object */
+  simpleParams?: boolean;
 }
 
-export interface PhotonMCPClass {
+export interface PhotonClass {
   name: string;
   description?: string;
   tools: PhotonTool[];
@@ -107,6 +202,9 @@ export interface PhotonMCPClass {
   classConstructor?: Record<string, Function>;
 }
 
+/** @deprecated Use PhotonClass instead */
+export type PhotonMCPClass = PhotonClass;
+
 export interface ConstructorParam {
   name: string;
   type: string;
@@ -154,7 +252,7 @@ export interface ResolvedInjection {
  *  * @mcp github anthropics/mcp-server-github
  *  * @mcp fs npm:@modelcontextprotocol/server-filesystem
  *  *\/
- * export default class MyPhoton extends PhotonMCP {
+ * export default class MyPhoton extends Photon {
  *   async doSomething() {
  *     const issues = await this.github.list_issues({ repo: 'owner/repo' });
  *   }
@@ -380,9 +478,9 @@ export interface StaticInfo {
 }
 
 /**
- * Extended PhotonMCPClass with templates and statics
+ * Extended PhotonClass with templates and statics
  */
-export interface PhotonMCPClassExtended extends PhotonMCPClass {
+export interface PhotonClassExtended extends PhotonClass {
   templates: TemplateInfo[];
   statics: StaticInfo[];
   /** Assets from the Photon's asset folder (UI, prompts, resources) */
@@ -391,6 +489,9 @@ export interface PhotonMCPClassExtended extends PhotonMCPClass {
   injectedPhotons?: string[];
 }
 
+/** @deprecated Use PhotonClassExtended instead */
+export type PhotonMCPClassExtended = PhotonClassExtended;
+
 // ══════════════════════════════════════════════════════════════════════════════
 // STATEFUL WORKFLOW TYPES
 // ══════════════════════════════════════════════════════════════════════════════
@@ -575,7 +676,7 @@ export interface ConfigParam {
  *
  * Example:
  * ```typescript
- * export default class MyPhoton extends PhotonMCP {
+ * export default class MyPhoton extends Photon {
  *   async configure(params: {
  *     apiEndpoint: string;
  *     maxRetries?: number;

package/src/utils/duration.ts

@@ -0,0 +1,67 @@
+/**
+ * Duration and rate parsing utilities for functional tags
+ *
+ * Supports duration strings: 30s, 5m, 1h, 1d, 500ms
+ * Supports rate expressions: 10/min, 100/h, 5/s
+ */
+
+const DURATION_MULTIPLIERS: Record<string, number> = {
+  ms: 1,
+  s: 1_000,
+  sec: 1_000,
+  m: 60_000,
+  min: 60_000,
+  h: 3_600_000,
+  hr: 3_600_000,
+  d: 86_400_000,
+  day: 86_400_000,
+};
+
+/**
+ * Parse a duration string into milliseconds
+ * @example parseDuration('30s') → 30000
+ * @example parseDuration('5m') → 300000
+ * @example parseDuration('500ms') → 500
+ * @example parseDuration('1234') → 1234 (raw ms fallback)
+ */
+export function parseDuration(input: string): number {
+  const trimmed = input.trim();
+  const match = trimmed.match(/^(\d+(?:\.\d+)?)(ms|s|sec|m|min|h|hr|d|day)$/i);
+  if (match) {
+    const value = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    return Math.round(value * DURATION_MULTIPLIERS[unit]);
+  }
+  // Fallback: raw milliseconds
+  const raw = parseInt(trimmed, 10);
+  return isNaN(raw) ? 0 : raw;
+}
+
+const RATE_WINDOW_MULTIPLIERS: Record<string, number> = {
+  s: 1_000,
+  sec: 1_000,
+  m: 60_000,
+  min: 60_000,
+  h: 3_600_000,
+  hr: 3_600_000,
+  d: 86_400_000,
+  day: 86_400_000,
+};
+
+/**
+ * Parse a rate expression into count and window
+ * @example parseRate('10/min') → { count: 10, windowMs: 60000 }
+ * @example parseRate('100/h') → { count: 100, windowMs: 3600000 }
+ */
+export function parseRate(input: string): { count: number; windowMs: number } {
+  const trimmed = input.trim();
+  const match = trimmed.match(/^(\d+)\/(s|sec|m|min|h|hr|d|day)$/i);
+  if (match) {
+    const count = parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    return { count, windowMs: RATE_WINDOW_MULTIPLIERS[unit] };
+  }
+  // Fallback: treat as count per minute
+  const count = parseInt(trimmed, 10);
+  return { count: isNaN(count) ? 10 : count, windowMs: 60_000 };
+}