@marktoflow/core 2.0.0-alpha.7 → 2.0.1

package/dist/permissions.js

@@ -0,0 +1,286 @@
+/**
+ * Permissions module for marktoflow v2.0
+ *
+ * Provides permission merging and enforcement utilities for step-level
+ * and workflow-level permission restrictions.
+ */
+import { minimatch } from 'minimatch';
+// ============================================================================
+// Permission Merging
+// ============================================================================
+/**
+ * Merge workflow-level and step-level permissions.
+ * Step permissions override workflow permissions, with most restrictive winning.
+ */
+export function mergePermissions(workflow, step) {
+    // Start with defaults (most permissive)
+    const effective = {
+        read: true,
+        write: true,
+        execute: true,
+        allowedCommands: [],
+        blockedCommands: [],
+        allowedDirectories: [],
+        blockedPaths: [],
+        network: true,
+        allowedHosts: [],
+        maxFileSize: undefined,
+    };
+    // Apply workflow-level permissions first
+    if (workflow) {
+        applyPermissions(effective, workflow);
+    }
+    // Apply step-level permissions (overrides workflow)
+    if (step) {
+        applyPermissions(effective, step);
+    }
+    return effective;
+}
+/**
+ * Apply a permission configuration to effective permissions.
+ */
+function applyPermissions(effective, perms) {
+    if (!perms)
+        return;
+    // File operations
+    if (perms.read !== undefined) {
+        effective.read = perms.read;
+    }
+    if (perms.write !== undefined) {
+        effective.write = perms.write;
+    }
+    // Command execution
+    if (perms.execute !== undefined) {
+        effective.execute = perms.execute;
+    }
+    if (perms.allowedCommands) {
+        // Merge allowed commands (union)
+        effective.allowedCommands = [
+            ...new Set([...effective.allowedCommands, ...perms.allowedCommands]),
+        ];
+    }
+    if (perms.blockedCommands) {
+        // Merge blocked commands (union)
+        effective.blockedCommands = [
+            ...new Set([...effective.blockedCommands, ...perms.blockedCommands]),
+        ];
+    }
+    // Directory restrictions
+    if (perms.allowedDirectories) {
+        effective.allowedDirectories = [
+            ...new Set([...effective.allowedDirectories, ...perms.allowedDirectories]),
+        ];
+    }
+    if (perms.blockedPaths) {
+        effective.blockedPaths = [
+            ...new Set([...effective.blockedPaths, ...perms.blockedPaths]),
+        ];
+    }
+    // Network
+    if (perms.network !== undefined) {
+        effective.network = perms.network;
+    }
+    if (perms.allowedHosts) {
+        effective.allowedHosts = [
+            ...new Set([...effective.allowedHosts, ...perms.allowedHosts]),
+        ];
+    }
+    // Limits (most restrictive wins)
+    if (perms.maxFileSize !== undefined) {
+        if (effective.maxFileSize === undefined) {
+            effective.maxFileSize = perms.maxFileSize;
+        }
+        else {
+            effective.maxFileSize = Math.min(effective.maxFileSize, perms.maxFileSize);
+        }
+    }
+}
+// ============================================================================
+// Permission Checking
+// ============================================================================
+/**
+ * Check if an operation is permitted.
+ */
+export function checkPermission(perms, operation, target) {
+    switch (operation) {
+        case 'read':
+            return checkFilePermission(perms.read, target, 'read', perms);
+        case 'write':
+            return checkFilePermission(perms.write, target, 'write', perms);
+        case 'execute':
+            return checkExecutePermission(perms, target);
+        case 'network':
+            return checkNetworkPermission(perms, target);
+        default:
+            return { allowed: false, reason: `Unknown operation: ${operation}` };
+    }
+}
+/**
+ * Check file operation permission (read/write).
+ */
+function checkFilePermission(permission, target, operation, perms) {
+    // If permission is false, deny all
+    if (!permission) {
+        return { allowed: false, reason: `${operation} operations are disabled` };
+    }
+    // If permission is true and no target, allow
+    if (permission === true && !target) {
+        return { allowed: true };
+    }
+    // Check blocked paths first
+    if (target && perms.blockedPaths.length > 0) {
+        for (const blocked of perms.blockedPaths) {
+            if (matchPath(target, blocked)) {
+                return { allowed: false, reason: `Path is blocked: ${blocked}` };
+            }
+        }
+    }
+    // Check allowed directories if specified
+    if (target && perms.allowedDirectories.length > 0) {
+        const inAllowedDir = perms.allowedDirectories.some((dir) => target.startsWith(dir) || matchPath(target, dir + '/**'));
+        if (!inAllowedDir) {
+            return { allowed: false, reason: `Path not in allowed directories` };
+        }
+    }
+    // If permission is an array, check if target matches any pattern
+    if (Array.isArray(permission)) {
+        if (!target) {
+            return { allowed: true }; // No specific target, allow
+        }
+        const matches = permission.some((pattern) => matchPath(target, pattern));
+        if (!matches) {
+            return { allowed: false, reason: `Path does not match allowed patterns for ${operation}` };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Check execute permission for a command.
+ */
+function checkExecutePermission(perms, command) {
+    // If execute is false, deny all
+    if (perms.execute === false) {
+        return { allowed: false, reason: 'Command execution is disabled' };
+    }
+    if (!command) {
+        return { allowed: true };
+    }
+    // Check blocked commands first
+    if (perms.blockedCommands.length > 0) {
+        for (const blocked of perms.blockedCommands) {
+            if (commandMatches(command, blocked)) {
+                return { allowed: false, reason: `Command is blocked: ${blocked}` };
+            }
+        }
+    }
+    // If execute is an array of allowed commands
+    if (Array.isArray(perms.execute)) {
+        const matches = perms.execute.some((allowed) => commandMatches(command, allowed));
+        if (!matches) {
+            return { allowed: false, reason: 'Command not in allowed list' };
+        }
+    }
+    // Check allowed commands if specified
+    if (perms.allowedCommands.length > 0) {
+        const matches = perms.allowedCommands.some((allowed) => commandMatches(command, allowed));
+        if (!matches) {
+            return { allowed: false, reason: 'Command not in allowed list' };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Check network permission for a host.
+ */
+function checkNetworkPermission(perms, host) {
+    // If network is false, deny all
+    if (!perms.network) {
+        return { allowed: false, reason: 'Network access is disabled' };
+    }
+    if (!host) {
+        return { allowed: true };
+    }
+    // Check allowed hosts if specified
+    if (perms.allowedHosts.length > 0) {
+        const matches = perms.allowedHosts.some((allowed) => hostMatches(host, allowed));
+        if (!matches) {
+            return { allowed: false, reason: `Host not in allowed list: ${host}` };
+        }
+    }
+    return { allowed: true };
+}
+// ============================================================================
+// Pattern Matching Helpers
+// ============================================================================
+/**
+ * Match a path against a glob pattern.
+ */
+function matchPath(path, pattern) {
+    return minimatch(path, pattern, { dot: true });
+}
+/**
+ * Check if a command matches a pattern.
+ * Patterns can be exact matches or wildcards.
+ */
+function commandMatches(command, pattern) {
+    // Exact match
+    if (command === pattern) {
+        return true;
+    }
+    // Check if command starts with pattern (for matching command prefixes like "rm -rf")
+    if (command.startsWith(pattern + ' ') || command.startsWith(pattern)) {
+        return true;
+    }
+    // Wildcard pattern matching
+    if (pattern.includes('*')) {
+        const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+        return regex.test(command);
+    }
+    return false;
+}
+/**
+ * Check if a host matches a pattern.
+ * Supports wildcard domains like *.example.com
+ */
+function hostMatches(host, pattern) {
+    // Exact match
+    if (host === pattern) {
+        return true;
+    }
+    // Wildcard domain matching (e.g., *.example.com)
+    if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(1); // .example.com
+        return host.endsWith(suffix);
+    }
+    return false;
+}
+/**
+ * Convert EffectivePermissions to a SecurityPolicy for use with hooks.
+ */
+export function toSecurityPolicy(perms) {
+    return {
+        allowFileRead: (path) => checkPermission(perms, 'read', path),
+        allowFileWrite: (path) => checkPermission(perms, 'write', path),
+        allowCommand: (command) => checkPermission(perms, 'execute', command),
+        allowNetwork: (host) => checkPermission(perms, 'network', host),
+        maxFileSize: perms.maxFileSize,
+    };
+}
+/**
+ * Create default (permissive) permissions.
+ */
+export function createDefaultPermissions() {
+    return {
+        read: true,
+        write: true,
+        execute: true,
+        allowedCommands: [],
+        blockedCommands: [],
+        allowedDirectories: [],
+        blockedPaths: [],
+        network: true,
+        allowedHosts: [],
+        maxFileSize: undefined,
+    };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

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

package/dist/prompt-loader.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Prompt Loader for marktoflow v2.0
+ *
+ * Loads external prompt files with optional YAML frontmatter for variable definitions.
+ * Supports template variable resolution using Nunjucks ({{ prompt.variable }} syntax).
+ */
+import { ExecutionContext } from './models.js';
+export interface PromptVariable {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    required: boolean | undefined;
+    default: unknown;
+    description: string | undefined;
+}
+export interface LoadedPrompt {
+    name: string | undefined;
+    description: string | undefined;
+    variables: Record<string, PromptVariable>;
+    content: string;
+    rawContent: string;
+    filePath: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface ResolvedPrompt {
+    content: string;
+    variables: Record<string, unknown>;
+}
+/**
+ * Load a prompt file with optional YAML frontmatter.
+ */
+export declare function loadPromptFile(promptPath: string, basePath?: string): Promise<LoadedPrompt>;
+/**
+ * Resolve {{ prompt.variable }} templates in a prompt using Nunjucks.
+ *
+ * Features enabled by using Nunjucks:
+ * - Filters: {{ prompt.name | upper }}, {{ value | split('/') | first }}
+ * - Conditionals: {% if prompt.enabled %}...{% endif %}
+ * - Loops: {% for item in items %}...{% endfor %}
+ * - All custom filters from nunjucks-filters.ts
+ */
+export declare function resolvePromptTemplate(prompt: LoadedPrompt, inputs: Record<string, unknown>, context?: ExecutionContext): ResolvedPrompt;
+/**
+ * Validate that all required prompt inputs are provided.
+ */
+export declare function validatePromptInputs(prompt: LoadedPrompt, inputs: Record<string, unknown>): ValidationResult;
+/**
+ * Extract all variable references from a prompt template.
+ */
+export declare function extractPromptVariables(content: string): string[];
+//# sourceMappingURL=prompt-loader.d.ts.map

package/dist/prompt-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-loader.d.ts","sourceRoot":"","sources":["../src/prompt-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAO/C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC3D,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAQD;;GAEG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,CA2DvB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,gBAAgB,GACzB,cAAc,CAwChB;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,gBAAgB,CAmClB;AAyCD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAWhE"}

package/dist/prompt-loader.js

@@ -0,0 +1,205 @@
+/**
+ * Prompt Loader for marktoflow v2.0
+ *
+ * Loads external prompt files with optional YAML frontmatter for variable definitions.
+ * Supports template variable resolution using Nunjucks ({{ prompt.variable }} syntax).
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { renderTemplate } from './template-engine.js';
+// ============================================================================
+// Prompt Loading
+// ============================================================================
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?/;
+/**
+ * Load a prompt file with optional YAML frontmatter.
+ */
+export async function loadPromptFile(promptPath, basePath) {
+    // Resolve path relative to base path if provided
+    const resolvedPath = basePath ? resolve(dirname(basePath), promptPath) : resolve(promptPath);
+    let content;
+    try {
+        content = await readFile(resolvedPath, 'utf-8');
+    }
+    catch (error) {
+        throw new Error(`Failed to load prompt file: ${resolvedPath}. ${error}`);
+    }
+    // Parse frontmatter if present
+    const frontmatterMatch = content.match(FRONTMATTER_REGEX);
+    let frontmatter = {};
+    let promptContent = content;
+    if (frontmatterMatch) {
+        try {
+            frontmatter = parseYaml(frontmatterMatch[1]);
+            promptContent = content.slice(frontmatterMatch[0].length).trim();
+        }
+        catch (error) {
+            throw new Error(`Invalid YAML frontmatter in prompt file: ${resolvedPath}. ${error}`);
+        }
+    }
+    // Extract variables
+    const variables = {};
+    const variablesRaw = frontmatter.variables;
+    if (variablesRaw) {
+        for (const [name, config] of Object.entries(variablesRaw)) {
+            if (typeof config === 'object' && config !== null) {
+                const varConfig = config;
+                variables[name] = {
+                    type: varConfig.type || 'string',
+                    required: varConfig.required,
+                    default: varConfig.default,
+                    description: varConfig.description,
+                };
+            }
+            else {
+                // Simple type definition
+                variables[name] = {
+                    type: config || 'string',
+                    required: undefined,
+                    default: undefined,
+                    description: undefined,
+                };
+            }
+        }
+    }
+    return {
+        name: frontmatter.name,
+        description: frontmatter.description,
+        variables,
+        content: promptContent,
+        rawContent: content,
+        filePath: resolvedPath,
+    };
+}
+// ============================================================================
+// Template Resolution
+// ============================================================================
+/**
+ * Resolve {{ prompt.variable }} templates in a prompt using Nunjucks.
+ *
+ * Features enabled by using Nunjucks:
+ * - Filters: {{ prompt.name | upper }}, {{ value | split('/') | first }}
+ * - Conditionals: {% if prompt.enabled %}...{% endif %}
+ * - Loops: {% for item in items %}...{% endfor %}
+ * - All custom filters from nunjucks-filters.ts
+ */
+export function resolvePromptTemplate(prompt, inputs, context) {
+    // Build resolved variables with defaults
+    const resolvedVars = {};
+    // Apply defaults first
+    for (const [name, config] of Object.entries(prompt.variables)) {
+        if (config.default !== undefined) {
+            resolvedVars[name] = config.default;
+        }
+    }
+    // Override with provided inputs
+    for (const [name, value] of Object.entries(inputs)) {
+        resolvedVars[name] = value;
+    }
+    // Build the template context
+    // 'prompt' namespace contains the resolved prompt variables
+    // Also include context variables if available
+    const templateContext = {
+        prompt: resolvedVars,
+        ...resolvedVars, // Also expose at top level for backward compatibility
+    };
+    // Add context variables if available
+    if (context) {
+        templateContext.inputs = context.inputs;
+        templateContext.variables = context.variables;
+        // Merge context variables at top level for convenience
+        Object.assign(templateContext, context.variables);
+    }
+    // Render template using Nunjucks
+    const rendered = renderTemplate(prompt.content, templateContext);
+    const content = typeof rendered === 'string' ? rendered : String(rendered);
+    return {
+        content,
+        variables: resolvedVars,
+    };
+}
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Validate that all required prompt inputs are provided.
+ */
+export function validatePromptInputs(prompt, inputs) {
+    const errors = [];
+    const warnings = [];
+    for (const [name, config] of Object.entries(prompt.variables)) {
+        const value = inputs[name];
+        const hasValue = value !== undefined && value !== null;
+        // Check required
+        if (config.required && !hasValue && config.default === undefined) {
+            errors.push(`Missing required prompt variable: ${name}`);
+            continue;
+        }
+        // Type validation (if value is provided)
+        if (hasValue) {
+            const typeError = validateType(value, config.type, name);
+            if (typeError) {
+                errors.push(typeError);
+            }
+        }
+    }
+    // Warn about unused inputs
+    for (const name of Object.keys(inputs)) {
+        if (!prompt.variables[name]) {
+            warnings.push(`Unused prompt input: ${name}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Validate a value against an expected type.
+ */
+function validateType(value, type, name) {
+    switch (type) {
+        case 'string':
+            if (typeof value !== 'string') {
+                return `Expected string for ${name}, got ${typeof value}`;
+            }
+            break;
+        case 'number':
+            if (typeof value !== 'number') {
+                return `Expected number for ${name}, got ${typeof value}`;
+            }
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                return `Expected boolean for ${name}, got ${typeof value}`;
+            }
+            break;
+        case 'array':
+            if (!Array.isArray(value)) {
+                return `Expected array for ${name}, got ${typeof value}`;
+            }
+            break;
+        case 'object':
+            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                return `Expected object for ${name}, got ${Array.isArray(value) ? 'array' : typeof value}`;
+            }
+            break;
+    }
+    return null;
+}
+/**
+ * Extract all variable references from a prompt template.
+ */
+export function extractPromptVariables(content) {
+    const variables = new Set();
+    // Extract {{ prompt.variable }} patterns
+    const promptVarRegex = /\{\{\s*prompt\.([^}]+)\s*\}\}/g;
+    let match;
+    while ((match = promptVarRegex.exec(content)) !== null) {
+        variables.add(match[1].trim());
+    }
+    return Array.from(variables);
+}
+//# sourceMappingURL=prompt-loader.js.map

package/dist/prompt-loader.js.map

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

package/dist/scheduler.d.ts

@@ -2,7 +2,10 @@
  * Scheduler for marktoflow v2.0
  *
  * Handles cron-based scheduling of workflow execution.
+ * Uses cron-parser for robust cron expression handling with proper
+ * DST handling, leap year support, and timezone awareness.
  */
+import { type CronExpression } from 'cron-parser';
 export interface ScheduledJob {
     id: string;
     workflowPath: string;
@@ -29,15 +32,31 @@ export declare class CronParser {
      * Special values: * (any), * /N (every N), N-M (range), N,M (list)
      */
     static parse(expression: string): CronFields;
-    private static parseField;
     /**
      * Check if a date matches a cron expression.
      */
     static matches(expression: string, date: Date): boolean;
     /**
      * Calculate the next run time for a cron expression.
+     * Supports timezone-aware scheduling.
      */
-    static nextRun(expression: string, after?: Date): Date | null;
+    static nextRun(expression: string, after?: Date, timezone?: string): Date | null;
+    /**
+     * Calculate the previous run time for a cron expression.
+     */
+    static prevRun(expression: string, before?: Date, timezone?: string): Date | null;
+    /**
+     * Validate a cron expression without throwing.
+     * Only accepts standard 5-field cron expressions.
+     */
+    static isValid(expression: string): boolean;
+    /**
+     * Get the underlying cron-parser CronExpression for advanced usage.
+     */
+    static getInterval(expression: string, options?: {
+        currentDate?: Date;
+        tz?: string;
+    }): CronExpression;
 }
 export declare class Scheduler {
     private checkIntervalMs;
@@ -87,5 +106,5 @@ export declare class Scheduler {
      */
     isRunning(): boolean;
 }
-export declare function createJob(id: string, workflowPath: string, schedule: string, inputs?: Record<string, unknown>): ScheduledJob;
+export declare function createJob(id: string, workflowPath: string, schedule: string, inputs?: Record<string, unknown>, timezone?: string): ScheduledJob;
 //# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAM/D,qBAAa,UAAU;IACrB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU;IAiC5C,OAAO,CAAC,MAAM,CAAC,UAAU;IAgCzB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO;IAgBvD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI;CA0B9D;AAMD,qBAAa,SAAS;IAMR,OAAO,CAAC,eAAe;IALnC,OAAO,CAAC,IAAI,CAAwC;IACpD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,SAAS,CAAqB;gBAElB,eAAe,GAAE,MAAc;IAEnD;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAM/B;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI/C;;OAEG;IACH,QAAQ,IAAI,YAAY,EAAE;IAI1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAIrC;;OAEG;IACH,KAAK,IAAI,IAAI;IAgBb;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;YACW,SAAS;IAuBvB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IA0B3C;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB;AAMD,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,YAAY,CAYd"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAMxE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAM/D,qBAAa,UAAU;IACrB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU;IAwB5C;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO;IAgBvD;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAYhF;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAYjF;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAkB3C;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,IAAI,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc;CAMtG;AAMD,qBAAa,SAAS;IAMR,OAAO,CAAC,eAAe;IALnC,OAAO,CAAC,IAAI,CAAwC;IACpD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,SAAS,CAAqB;gBAElB,eAAe,GAAE,MAAc;IAEnD;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAM/B;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI/C;;OAEG;IACH,QAAQ,IAAI,YAAY,EAAE;IAI1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAIrC;;OAEG;IACH,KAAK,IAAI,IAAI;IAgBb;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;YACW,SAAS;IAuBvB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IA0B3C;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB;AAMD,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,QAAQ,GAAE,MAAc,GACvB,YAAY,CAYd"}