@pikku/core 0.12.72 → 0.12.77

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

@@ -1,4 +1,5 @@
-import type { SecretService } from './secret-service.js';
+import type { SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 export interface CredentialStatus {
     secretId: string;
     name: string;
@@ -18,21 +19,14 @@ 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]>;
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<K extends keyof TMap & string>(key: K): Promise<SecretValue<TMap[K]>>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     getAllStatus(): Promise<CredentialStatus[]>;
     getMissing(): Promise<CredentialStatus[]>;
 }

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,32 @@
+import type { Safe } from '../secret-value.js';
 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 +36,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 +60,6 @@ export interface WebhookDeliveryRecord {
     updatedAt: Date;
     deliveredAt: Date | null;
 }
-/** A single persisted delivery attempt. */
 export interface WebhookAttemptRecord {
     attemptId: string;
     deliveryId: string;
@@ -97,44 +69,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...`).
-     */
+    abstract send<T extends SendWebhookInput>(input: Safe<T>): Promise<SendWebhookResult>;
+    /** 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', {});
@@ -559,16 +542,16 @@ export function defineServiceTests(config) {
                     endpoint: 'https://api.example.com',
                 });
                 const result = await service.getSecret('api-key');
-                assert.deepEqual(result, {
+                assert.deepEqual(result.reveal(), {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
                 });
             });
-            test('getSecret returns raw string', async () => {
+            test('getSecret wraps the raw string rather than returning it', async () => {
                 const service = await factory({ key: kek });
                 await service.setSecret('string-secret', 'plain-value');
                 const result = await service.getSecret('string-secret');
-                assert.strictEqual(result, 'plain-value');
+                assert.strictEqual(result.reveal(), 'plain-value');
             });
             test('hasSecret returns true/false', async () => {
                 const service = await factory({ key: kek });
@@ -586,7 +569,7 @@ export function defineServiceTests(config) {
                 await service.setSecret('upsert-key', { v: 1 });
                 await service.setSecret('upsert-key', { v: 2 });
                 const result = await service.getSecret('upsert-key');
-                assert.deepEqual(result, { v: 2 });
+                assert.deepEqual(result.reveal(), { v: 2 });
             });
             test('deleteSecret removes the key', async () => {
                 const service = await factory({ key: kek });
@@ -605,7 +588,7 @@ export function defineServiceTests(config) {
                     previousKey: kek,
                 });
                 const before = await rotatedService.getSecret('rotate-test');
-                assert.deepEqual(before, { important: 'data' });
+                assert.deepEqual(before.reveal(), { important: 'data' });
                 assert.ok(rotatedService.rotateKEK);
                 const count = await rotatedService.rotateKEK();
                 assert.ok(count > 0);
@@ -614,7 +597,7 @@ export function defineServiceTests(config) {
                     keyVersion: 2,
                 });
                 const after = await newOnlyService.getSecret('rotate-test');
-                assert.deepEqual(after, { important: 'data' });
+                assert.deepEqual(after.reveal(), { important: 'data' });
             });
             test('rotateKEK throws without previousKey', async () => {
                 const service = await factory({ key: kek });

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' ||