@pikku/core 0.12.71 → 0.12.74

package/dist/services/stub-tracker.js

@@ -1,8 +1,7 @@
 /**
- * Tracks calls made to stubbed services and enforces strict mode:
- * once a scenario asserts any call on a service, every recorded call on that
- * service must be verified by end of scenario — otherwise the After hook fails.
- * Services never touched by an assertion stay lenient.
+ * Strict per service: once a scenario asserts any call on a service, every
+ * recorded call on it must be verified by the end of the scenario or the After
+ * hook fails. A service no assertion ever touched stays lenient.
  */
 export class StubTracker {
     calls = new Map();
@@ -87,16 +86,11 @@ export class StubTracker {
         }
     }
 }
-/**
- * Creates a Proxy suitable for passing as `existingServices` to
- * `createSingletonServices`. Every property returns `tracker.stub(prop)`
- * EXCEPT `schema`, which returns `undefined` so the service factory creates
- * a real schema service. Stubbing the schema makes validation a no-op —
- * required fields pass silently and tests validate nothing.
- */
+/** Pass as `existingServices` to `createSingletonServices`. */
 export function createStubProxy(tracker) {
     return new Proxy({}, {
         get(_, prop) {
+            // knowledge: decisions/internals/the-schema-service-is-never-stubbed.md
             if (prop === 'schema')
                 return undefined;
             return tracker.stub(prop);
@@ -104,16 +98,12 @@ export function createStubProxy(tracker) {
     });
 }
 const defaultStubTracker = new StubTracker();
-/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+/** The process-wide tracker `stub()`/`spy()` record into; read by the console's getStubCalls/resetStubs RPCs. */
 export const getStubTracker = () => defaultStubTracker;
-/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+/** True when the server was started by `pikku dev --test`, which sets PIKKU_TEST_RUN. */
 export const isTestRun = () => globalThis
     .process?.env?.PIKKU_TEST_RUN === 'true';
-/**
- * Creates a recording fake for a service. Methods present on `impl` run and
- * their result is returned; missing methods resolve `undefined`. Every call
- * is recorded so scenarios can assert via workflow.expectService().
- */
+/** Methods on `impl` run and return; every other method resolves `undefined`. */
 export function stub(service, impl) {
     return new Proxy((impl ?? {}), {
         get(target, method) {

package/dist/services/system-role-guard.d.ts

@@ -0,0 +1,33 @@
+import type { Role } from './scope-service.js';
+/**
+ * The guards a {@link ScopeService} implementation must apply before mutating
+ * a role.
+ *
+ * Shared rather than left to each implementation because the rule is a
+ * contract, not a policy: a store that lets the console delete `buyer` makes
+ * every persona and scenario written against `buyer` silently stop testing
+ * what it claims to, and nothing fails at the point of the mistake. Two
+ * implementations disagreeing about that would be worse than either rule.
+ *
+ * `isSystemRole` is passed in rather than a role list, so an implementation can
+ * answer it from a column, a cached set, or a query, whichever is cheap.
+ */
+export type IsSystemRole = (name: string) => boolean | Promise<boolean>;
+/**
+ * Refuses a destructive or re-scoping operation against a declared role.
+ *
+ * @param operation a verb phrase for the message, e.g. `'delete role'`.
+ */
+export declare const assertRoleIsMutable: (name: string, isSystemRole: IsSystemRole, operation: string) => Promise<void>;
+/**
+ * Refuses a new custom role that would shadow a declared one.
+ */
+export declare const assertRoleNameAvailable: (name: string, isSystemRole: IsSystemRole) => Promise<void>;
+/**
+ * Why the console must render a role as locked, or `null` when it is editable.
+ *
+ * Returned rather than a boolean so the UI shows a reason instead of a
+ * disabled button with no explanation — the difference between a user filing a
+ * bug and a user editing the declaration.
+ */
+export declare const roleLockReason: (role: Role) => string | null;

package/dist/services/system-role-guard.js

@@ -0,0 +1,38 @@
+import { SystemRoleImmutableError, SystemRoleShadowedError, } from '../errors/errors.js';
+/**
+ * Refuses a destructive or re-scoping operation against a declared role.
+ *
+ * @param operation a verb phrase for the message, e.g. `'delete role'`.
+ */
+export const assertRoleIsMutable = async (name, isSystemRole, operation) => {
+    if (await isSystemRole(name)) {
+        throw new SystemRoleImmutableError(name, operation);
+    }
+};
+/**
+ * Refuses a new custom role that would shadow a declared one.
+ */
+export const assertRoleNameAvailable = async (name, isSystemRole) => {
+    if (await isSystemRole(name)) {
+        throw new SystemRoleShadowedError(name);
+    }
+};
+/**
+ * Why the console must render a role as locked, or `null` when it is editable.
+ *
+ * Returned rather than a boolean so the UI shows a reason instead of a
+ * disabled button with no explanation — the difference between a user filing a
+ * bug and a user editing the declaration.
+ */
+export const roleLockReason = (role) => {
+    if (!role.system) {
+        return null;
+    }
+    if (role.declared === false) {
+        return (`'${role.name}' was declared in code and that declaration has been removed. ` +
+            `It is inert: still held by its current members, not offered for new grants. ` +
+            `Run 'pikku roles prune' to remove it.`);
+    }
+    return (`'${role.name}' is declared in code with defineSystemRole. ` +
+        `Edit the declaration to change what it grants.`);
+};

package/dist/services/trigger-service.d.ts

@@ -1,16 +1,4 @@
-/**
- * Abstract TriggerService interface.
- *
- * Implementations manage trigger subscriptions — listening to external events
- * and dispatching to RPC targets or workflow starts.
- */
 export interface TriggerService {
-    /**
-     * Start all triggers
-     */
     start(): Promise<void>;
-    /**
-     * Stop all triggers
-     */
     stop(): Promise<void>;
 }

package/dist/services/typed-secret-service.d.ts

@@ -18,13 +18,6 @@ export type CredentialMeta = {
 export declare class TypedSecretService<TMap = Record<string, unknown>> implements SecretService {
     private secrets;
     private credentialsMeta;
-    /**
-     * In-process cache of resolved secrets, so callers can read naively without
-     * re-hitting the underlying service on every call. Only successful reads are
-     * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
-     * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
-     * until restart (see pikkujs/pikku#964).
-     */
     private cache;
     constructor(secrets: SecretService, credentialsMeta: Record<string, CredentialMeta>);
     getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;

package/dist/services/typed-secret-service.js

@@ -1,13 +1,7 @@
 export class TypedSecretService {
     secrets;
     credentialsMeta;
-    /**
-     * In-process cache of resolved secrets, so callers can read naively without
-     * re-hitting the underlying service on every call. Only successful reads are
-     * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
-     * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
-     * until restart (see pikkujs/pikku#964).
-     */
+    // knowledge: decisions/internals/typed-secret-service-caches-for-the-process-lifetime.md
     cache = new Map();
     constructor(secrets, credentialsMeta) {
         this.secrets = secrets;

package/dist/services/v8-coverage-service.d.ts

@@ -60,9 +60,8 @@ export interface CoverageFunctionMeta {
 export interface CoverageService {
     start(): Promise<void>;
     takeCoverage(): Promise<CoverageSnapshot>;
-    /** Maps the current snapshot onto function body spans. Provided by the
-     *  process that booted the coverage backend (the pikku CLI) — absent when
-     *  the runtime only exposes raw snapshots. */
+    /** Provided by the process that booted the backend (the pikku CLI); absent
+     *  when the runtime only exposes raw snapshots. */
     takeReport?(functionsMeta: Record<string, CoverageFunctionMeta>): Promise<FunctionCoverageReport>;
     reset(): Promise<void>;
     stop(): Promise<void>;

package/dist/services/v8-coverage-service.js

@@ -1,5 +1,3 @@
-// node:inspector is imported lazily inside start() so this module stays
-// loadable on runtimes without it (e.g. Cloudflare Workers).
 export class V8CoverageService {
     session = null;
     startPromise = null;
@@ -17,6 +15,7 @@ export class V8CoverageService {
         return this.startPromise;
     }
     async doStart() {
+        // knowledge: decisions/internals/node-only-builtins-are-imported-dynamically.md
         const inspector = await import('node:inspector');
         this.session = new inspector.Session();
         this.session.connect();

package/dist/services/variables-service.d.ts

@@ -1,13 +1,6 @@
 export interface VariablesService {
     get<T = string>(name: string): Promise<T | undefined> | T | undefined;
-    /**
-     * Retrieves multiple variables in a single batch operation, mirroring
-     * `SecretService.getSecrets`. Missing variables are omitted rather than
-     * throwing, so the result is typed as `Partial<T>` and callers must handle
-     * keys that may be absent at runtime. Pass a shape as `T` to get a typed
-     * result without casting, e.g.
-     * `await variables.getVariables<{ FOO: string; BAR: string }>(['FOO', 'BAR'])`.
-     */
+    /** Same contract as `SecretService.getSecrets`: missing keys are omitted, hence `Partial<T>`. */
     getVariables<T extends Record<string, unknown> = Record<string, unknown>>(names: (keyof T & string)[]): Promise<Partial<T>> | Partial<T>;
     getAll: () => Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
     set: (name: string, value: unknown) => Promise<void> | void;

package/dist/services/webhook-service.d.ts

@@ -1,54 +1,31 @@
 export interface SendWebhookInput {
-    /** The endpoint the webhook is delivered to via HTTP POST. */
     url: string;
-    /** Optional event name, sent as the `X-Pikku-Event` header. */
+    /** Sent as the `X-Pikku-Event` header. */
     event?: string;
-    /** The payload, JSON-serialized into the request body. */
     data: unknown;
-    /** Extra headers merged over the defaults. */
     headers?: Record<string, string>;
-    /**
-     * Raw HMAC signing key for this delivery. Overrides the config-level
-     * secret. When present, the body is signed into the signature header.
-     */
+    /** A raw HMAC key, not a secret name — overrides `config.webhook.secret`. */
     secret?: string;
-    /** Retry count for failed deliveries. Overrides `config.webhook.retries`. */
+    /** Overrides `config.webhook.retries`. */
     retries?: number;
-    /**
-     * Delay between retries (`30000` or `'30s'`). A concrete value selects a
-     * fixed backoff; when omitted, backoff is exponential.
-     */
+    /** A concrete delay (`30000` or `'30s'`) selects fixed backoff; omitted means exponential. */
     retryDelay?: string | number;
-    /**
-     * Organization this delivery belongs to. Persisted by a store-backed
-     * implementation (e.g. `KyselyWebhookService`) so deliveries can be
-     * queried per org; ignored by the queue-only default.
-     */
+    /** Persisted only by store-backed implementations; the queue-only default ignores it. */
     organizationId?: string;
 }
 export interface SendWebhookResult {
     jobId: string;
 }
 export interface WebhookServiceConfig {
-    /** Default retry count for failed deliveries. */
     retries?: number;
-    /** Default delay between retries; omitted means exponential backoff. */
+    /** Omitted means exponential backoff. */
     retryDelay?: string | number;
-    /**
-     * Name of a secret (resolved through the secret service) used as the
-     * default HMAC signing key for all outgoing webhooks.
-     */
+    /** A secret *name* resolved through the secret service, unlike `SendWebhookInput.secret`. */
     secret?: string;
-    /**
-     * Header the body signature is sent in. Defaults to
-     * {@link DEFAULT_WEBHOOK_SIGNATURE_HEADER}.
-     */
     signatureHeader?: string;
     /**
-     * SSRF allowlist of hostnames outgoing webhooks may be delivered to. When set,
-     * a delivery target must be on this list. When omitted, obvious private and
-     * internal hosts (loopback, private ranges, cloud metadata) are blocked and
-     * all other public hosts are permitted.
+     * SSRF allowlist. Set: only these hostnames may be delivered to. Omitted:
+     * private/internal hosts are blocked and every other public host is allowed.
      */
     allowedHosts?: string[];
 }
@@ -58,24 +35,19 @@ export interface WebhookJobData {
     body: string;
     headers: Record<string, string>;
     /**
-     * Delivery-record id, present when a store-backed implementation enqueued
-     * the job. The worker keys its per-attempt records off this (it doubles as
-     * the queue `jobId`), so it's stable across retries.
+     * Present only when a store-backed implementation enqueued the job. Doubles
+     * as the queue `jobId`, so it is stable across retries.
      */
     deliveryId?: string;
 }
-/** Outcome of one delivery attempt, recorded against a delivery. */
 export interface WebhookAttemptResult {
-    /** HTTP status of the response, absent if the request never completed. */
+    /** Absent when the request never completed. */
     statusCode?: number;
-    /** Response body (truncated) — captured on failure for debugging. */
+    /** Truncated; captured on failure only. */
     responseBody?: string;
-    /** Network/timeout error message, when the request threw. */
     error?: string;
-    /** Whether this attempt was a 2xx success. */
     delivered: boolean;
 }
-/** A persisted webhook delivery, as surfaced to the console. */
 export interface WebhookDeliveryRecord {
     deliveryId: string;
     organizationId: string | null;
@@ -87,7 +59,6 @@ export interface WebhookDeliveryRecord {
     updatedAt: Date;
     deliveredAt: Date | null;
 }
-/** A single persisted delivery attempt. */
 export interface WebhookAttemptRecord {
     attemptId: string;
     deliveryId: string;
@@ -97,44 +68,29 @@ export interface WebhookAttemptRecord {
     error: string | null;
     createdAt: Date;
 }
-/** A delivery with its full attempt history. */
 export interface WebhookDeliveryWithAttempts {
     delivery: WebhookDeliveryRecord;
     attempts: WebhookAttemptRecord[];
 }
 export declare const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = "pikku-outgoing-webhooks";
 export declare const DEFAULT_WEBHOOK_SIGNATURE_HEADER = "X-Pikku-Signature";
-/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
 export declare const DEFAULT_WEBHOOK_RETRIES = 3;
-/**
- * Outgoing webhook delivery. {@link QueueWebhookService} is the default
- * implementation; apps can extend this to deliver directly, or through a
- * provider such as Svix.
- */
 export declare abstract class WebhookService {
     abstract send(input: SendWebhookInput): Promise<SendWebhookResult>;
-    /**
-     * Sign a body with HMAC-SHA256, producing the signature header value
-     * (e.g. `sha256=abc123...`).
-     */
+    /** Produces the header value, `sha256=<hex>`, not the bare digest. */
     protected sign(secret: string, body: string): string;
-    /**
-     * Verify a signature produced by {@link WebhookService.sign} — for
-     * receivers, which share the signing scheme.
-     */
+    /** Public because receivers verify with it; they share the signing scheme. */
     verify(secret: string, signature: string, body: string): boolean;
     /**
-     * Record a delivery attempt and roll the delivery's status/attempt-count
-     * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
-     * default queue-only service keeps no history, so this throws — a store-backed
-     * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+     * The three methods below are optional capability: the default queue-only
+     * service keeps no history and throws, and a store-backed implementation
+     * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
      */
     recordAttempt(_deliveryId: string, _result: WebhookAttemptResult): Promise<void>;
-    /** List deliveries, most recent first, optionally scoped to an org. */
+    /** Most recent first. */
     listDeliveries(_opts?: {
         organizationId?: string;
         limit?: number;
     }): Promise<WebhookDeliveryRecord[]>;
-    /** A single delivery with its attempt history, or null if unknown. */
     getDelivery(_deliveryId: string): Promise<WebhookDeliveryWithAttempts | null>;
 }

package/dist/services/webhook-service.js

@@ -2,42 +2,28 @@ import { NotImplementedError } from '../errors/errors.js';
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js';
 export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks';
 export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature';
-/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
 export const DEFAULT_WEBHOOK_RETRIES = 3;
-/**
- * Outgoing webhook delivery. {@link QueueWebhookService} is the default
- * implementation; apps can extend this to deliver directly, or through a
- * provider such as Svix.
- */
 export class WebhookService {
-    /**
-     * Sign a body with HMAC-SHA256, producing the signature header value
-     * (e.g. `sha256=abc123...`).
-     */
+    /** Produces the header value, `sha256=<hex>`, not the bare digest. */
     sign(secret, body) {
         return `sha256=${hmacSha256Hex(secret, body)}`;
     }
-    /**
-     * Verify a signature produced by {@link WebhookService.sign} — for
-     * receivers, which share the signing scheme.
-     */
+    /** Public because receivers verify with it; they share the signing scheme. */
     verify(secret, signature, body) {
         return timingSafeStringEqual(this.sign(secret, body), signature);
     }
     /**
-     * Record a delivery attempt and roll the delivery's status/attempt-count
-     * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
-     * default queue-only service keeps no history, so this throws — a store-backed
-     * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+     * The three methods below are optional capability: the default queue-only
+     * service keeps no history and throws, and a store-backed implementation
+     * (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides them.
      */
     recordAttempt(_deliveryId, _result) {
         throw new NotImplementedError('webhook delivery persistence is not configured');
     }
-    /** List deliveries, most recent first, optionally scoped to an org. */
+    /** Most recent first. */
     listDeliveries(_opts) {
         throw new NotImplementedError('webhook delivery persistence is not configured');
     }
-    /** A single delivery with its attempt history, or null if unknown. */
     getDelivery(_deliveryId) {
         throw new NotImplementedError('webhook delivery persistence is not configured');
     }

package/dist/services/workflow-service.d.ts

@@ -1,10 +1,6 @@
 import type { SerializedError } from '../types/core.types.js';
 import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run-timeline.js';
-/**
- * Interface for workflow orchestration
- * Handles workflow execution, replay, orchestration logic, and run-level state
- */
 export interface WorkflowService {
     wireQueueWorkers?(): void;
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
@@ -23,10 +19,8 @@ export interface WorkflowService {
     close(): Promise<void>;
     resumeWorkflow(runId: string): Promise<void>;
     /**
-     * Record a human decision against a `workflow.approval()` gate and wake the
-     * run. The payload is stored as given and validated on replay, inside the
-     * workflow body — so an invalid one re-closes the gate rather than failing the
-     * run. `reason` addresses the gate's first reach.
+     * The payload is stored as given and validated on replay inside the workflow
+     * body, so an invalid one re-closes the gate rather than failing the run.
      */
     approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
@@ -35,13 +29,7 @@ export interface WorkflowService {
     }): Promise<{
         runId: string;
     }>;
-    /**
-     * Start a run and wait for it to end.
-     *
-     * `pollIntervalMs` is the ceiling on the wait between reads of the run, not a
-     * fixed cadence: polling starts far shorter than this and widens towards it,
-     * so a run that finishes quickly is not held for a whole interval.
-     */
+    /** `pollIntervalMs` is a CEILING on the wait between reads, not a cadence. */
     runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;

package/dist/testing/service-tests.js

@@ -54,20 +54,16 @@ export function defineServiceTests(config) {
                     channelId: 'ch-state',
                     channelName: 'test-channel',
                 });
-                // initially undefined
                 const empty = await store.getState('ch-state');
                 assert.equal(empty, undefined);
-                // set + get
                 const payload = { userId: 'u-7', meta: { foo: 1 } };
                 await store.setState('ch-state', payload);
                 const got = await store.getState('ch-state');
                 assert.deepEqual(got, payload);
-                // overwrite
                 const next = { userId: 'u-8' };
                 await store.setState('ch-state', next);
                 const got2 = await store.getState('ch-state');
                 assert.deepEqual(got2, next);
-                // clear
                 await store.clearState('ch-state');
                 const after = await store.getState('ch-state');
                 assert.equal(after, undefined);
@@ -210,19 +206,6 @@ export function defineServiceTests(config) {
                 assert.equal(flaky.status, 'succeeded', 'latest attempt wins');
                 assert.equal(flaky.attempts, 2, 'attempt count surfaces in status');
             });
-            test('getNodesWithoutSteps', async () => {
-                const runId = await service.createRun('graph-workflow', {}, false, 'hash-7', wire);
-                await service.insertStepState(runId, 'existing-node', 'rpc', {});
-                const missing = await service.getNodesWithoutSteps(runId, [
-                    'existing-node',
-                    'missing-node',
-                ]);
-                assert.deepEqual(missing, ['missing-node']);
-            });
-            test('getNodesWithoutSteps with empty array', async () => {
-                const result = await service.getNodesWithoutSteps('any-id', []);
-                assert.deepEqual(result, []);
-            });
             test('getNodeResults', async () => {
                 const runId = await service.createRun('results-workflow', {}, false, 'hash-8', wire);
                 const step = await service.insertStepState(runId, 'node-a', 'rpc', {});

package/dist/time-utils.d.ts

@@ -4,23 +4,7 @@ export interface RelativeTimeInput {
     unit: TimeUnit;
 }
 export declare const getRelativeTimeOffset: ({ value, unit, }: RelativeTimeInput) => number;
-/**
- * Returns a Unix timestamp (in seconds) offset from now by the given duration.
- * e.g. value = -1 and unit = 'day' => 1 day ago => now - 86400 seconds
- */
 export declare const getRelativeTimeOffsetFromNow: (relativeTime: RelativeTimeInput) => Date;
-/**
- * Get duration in milliseconds from a string or number
- * @param duration
- * @returns
- */
 export declare const getDurationInMilliseconds: (duration: string | number) => number;
-/**
- * Parse a duration string to milliseconds
- * Supports formats like: '2s', '5s', '5sec', '5seconds', '5m', '5min', '5minutes', '1h', '1hour', '2d', '2day', '1w', '1week'
- *
- * @param duration - Duration string (e.g., '2s', '5min', '2hours', '1day')
- * @returns Duration in milliseconds
- */
 export declare const parseDurationString: (duration: string) => number;
 export {};

package/dist/time-utils.js

@@ -7,33 +7,17 @@ const multipliers = {
     year: Math.round(365.25 * 60 * 60 * 24),
 };
 export const getRelativeTimeOffset = ({ value, unit, }) => {
-    return Math.round(value * multipliers[unit]) * 1000; // convert to milliseconds
+    return Math.round(value * multipliers[unit]) * 1000;
 };
-/**
- * Returns a Unix timestamp (in seconds) offset from now by the given duration.
- * e.g. value = -1 and unit = 'day' => 1 day ago => now - 86400 seconds
- */
 export const getRelativeTimeOffsetFromNow = (relativeTime) => {
     return new Date(Date.now() + getRelativeTimeOffset(relativeTime));
 };
-/**
- * Get duration in milliseconds from a string or number
- * @param duration
- * @returns
- */
 export const getDurationInMilliseconds = (duration) => {
     if (typeof duration === 'number') {
         return duration;
     }
     return parseDurationString(duration);
 };
-/**
- * Parse a duration string to milliseconds
- * Supports formats like: '2s', '5s', '5sec', '5seconds', '5m', '5min', '5minutes', '1h', '1hour', '2d', '2day', '1w', '1week'
- *
- * @param duration - Duration string (e.g., '2s', '5min', '2hours', '1day')
- * @returns Duration in milliseconds
- */
 export const parseDurationString = (duration) => {
     const match = duration.match(/^(\d+)(ms|milliseconds?|s|sec|seconds?|m|min|minutes?|h|hour|hours?|d|day|days?|w|week|weeks?|y|year|years?)$/);
     if (!match) {
@@ -41,13 +25,11 @@ export const parseDurationString = (duration) => {
     }
     const value = parseInt(match[1], 10);
     const unitStr = match[2];
-    // Handle milliseconds specially
     if (unitStr === 'ms' ||
         unitStr === 'millisecond' ||
         unitStr === 'milliseconds') {
         return value;
     }
-    // Map string variations to TimeUnit
     let unit;
     if (unitStr === 's' ||
         unitStr === 'sec' ||