@t4h.framework/sleep 0.0.0-experimental-20260907052843

package/.ai/skills/framework-sleep/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: framework-sleep
+description: >-
+  Guides correct use of @t4h.framework/sleep in workflows: SleepActivity, duration
+  parsing, and async timeout behavior. Use when implementing delays in workflows,
+  working in packages/sleep, or testing sleep with TestWorkflowEnvironment timeout
+  outcomes.
+---
+
+# @t4h.framework/sleep
+
+Non-blocking sleep for workflows. Package path: `framework/packages/sleep`. Peer dependency: `@t4h.framework/core`.
+
+## Import surface
+
+```typescript
+import { sleep, SleepActivity } from '@t4h.framework/sleep'
+```
+
+## Workflow usage
+
+```typescript
+import { sleep } from '@t4h.framework/sleep'
+
+await sleep('30 seconds')
+await sleep('30 days')
+await sleep('30s')
+await sleep(5000)
+```
+
+## Duration formats
+
+- Number: milliseconds (`5000`)
+- Abbreviated: `500ms`, `30s`, `5m`, `1h`, `1d`
+- Full words: `30 seconds`, `2 minutes`, `1 hour`, `30 days` (singular or plural)
+
+## Testing
+
+`sleep` schedules a `SleepActivity` (an async activity that completes via
+`onTimeout`). `TestWorkflowEnvironment` from `@t4h.framework/core/testing`
+auto-resolves timeout-based activities by default (`resolveActivityTimeouts`), so
+a plain `execute()` advances the clock past the sleep:
+
+```typescript
+import { TestWorkflowEnvironment } from '@t4h.framework/core/testing'
+
+const env = TestWorkflowEnvironment.create({ now: 0 })
+const output = await env.execute(workflow, input)
+// env.clock advances to the sleep's timeout automatically
+```
+
+For explicit control, drive it with the `mockAsync()` builder and the `timeout()`
+outcome (which runs the activity's real `onTimeout`):
+
+```typescript
+import { mockAsync, timeout } from '@t4h.framework/core/testing'
+
+await env.execute(workflow, input, {
+  mockAsyncActivity: mockAsync().on(SleepActivity, timeout()),
+})
+```
+
+See the **framework-workflow-testing** skill for the full harness API.

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @t4h.framework/sleep
+
+## 0.0.0-experimental-20260907052843
+
+### Patch Changes
+
+- Updated dependencies [[`a30386e`](https://github.com/tech4humans-brasil/framework/commit/a30386ebf832d1eec5989b0a12a56d91a6999421)]:
+  - @t4h.framework/core@0.0.0-experimental-20260907052843
+
+## 0.2.0
+
+### Patch Changes
+
+- Update skills ([`6d7e7bc`](https://github.com/tech4humans-brasil/framework/commit/6d7e7bca0c780a9c53a0c9e5aa0a865c5af67959))
+
+## 0.1.0
+
+### Minor Changes
+
+- Implements sleep package ([#96](https://github.com/tech4humans-brasil/framework/pull/96))

package/README.md

@@ -0,0 +1,27 @@
+# @t4h.framework/sleep
+
+Non-blocking sleep for workflows.
+
+## Usage
+
+```typescript
+import { sleep } from '@t4h.framework/sleep'
+
+await sleep('30 seconds')
+await sleep('30 days')
+await sleep('30s')
+await sleep('1h')
+await sleep(5000)
+```
+
+## Duration formats
+
+| Form        | Examples                                       |
+| ----------- | ---------------------------------------------- |
+| Number (ms) | `5000`                                         |
+| Abbreviated | `500ms`, `30s`, `5m`, `1h`, `1d`               |
+| Full words  | `30 seconds`, `2 minutes`, `1 hour`, `30 days` |
+
+Singular and plural units are supported (`second` / `seconds`, `day` / `days`, etc.).
+
+Peer dependency: `@t4h.framework/core`.

package/dist/activities/SleepActivity.d.ts

@@ -0,0 +1,13 @@
+import { AsyncActivity } from '@t4h.framework/core';
+export type SleepActivityInput = {
+    durationInMs: number;
+};
+export declare class SleepActivity extends AsyncActivity<readonly [duration: number | string], SleepActivityInput, void, void, SleepActivityInput, never> {
+    toInput(duration: number | string): SleepActivityInput;
+    bootstrap(input: SleepActivityInput): import("@t4h.framework/core").AsyncActivityResultPending<SleepActivityInput, never>;
+    advance(): import("@t4h.framework/core").AsyncActivityResultRejected<void | import("@t4h.framework/core").Serializable>;
+    onTimeout(): import("@t4h.framework/core").AsyncActivityResultFulfilled<void | undefined>;
+    toOutput(): undefined;
+}
+export declare function sleep(duration: number | string): Promise<void>;
+//# sourceMappingURL=SleepActivity.d.ts.map

package/dist/activities/SleepActivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SleepActivity.d.ts","sourceRoot":"","sources":["../../src/activities/SleepActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAW,MAAM,qBAAqB,CAAA;AAI5D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,qBAAa,aAAc,SAAQ,aAAa,CAC9C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,EACpC,kBAAkB,EAClB,IAAI,EACJ,IAAI,EACJ,kBAAkB,EAClB,KAAK,CACN;IACQ,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB;IAItD,SAAS,CAAC,KAAK,EAAE,kBAAkB;IAOnC,OAAO;IAIP,SAAS;IAIT,QAAQ;CAGhB;AAED,wBAAsB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE"}

package/dist/activities/SleepActivity.js

@@ -0,0 +1,27 @@
+import { AsyncActivity, History } from '@t4h.framework/core';
+import { parseDuration } from '../utils/parse-duration.js';
+export class SleepActivity extends AsyncActivity {
+    toInput(duration) {
+        return { durationInMs: parseDuration(duration) };
+    }
+    bootstrap(input) {
+        return this.pending({
+            payload: input,
+            timeoutAt: new Date(Date.now() + input.durationInMs),
+        });
+    }
+    advance() {
+        return this.rejected({ reason: 'sleep cannot be advanced manually' });
+    }
+    onTimeout() {
+        return this.done();
+    }
+    toOutput() {
+        return undefined;
+    }
+}
+export async function sleep(duration) {
+    const handle = await History.reconciler(SleepActivity, duration);
+    await handle.wait();
+}
+//# sourceMappingURL=SleepActivity.js.map

package/dist/activities/SleepActivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SleepActivity.js","sourceRoot":"","sources":["../../src/activities/SleepActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAM1D,MAAM,OAAO,aAAc,SAAQ,aAOlC;IACQ,OAAO,CAAC,QAAyB;QACtC,OAAO,EAAE,YAAY,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAA;IAClD,CAAC;IAEM,SAAS,CAAC,KAAyB;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC;YAClB,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,YAAY,CAAC;SACrD,CAAC,CAAA;IACJ,CAAC;IAEM,OAAO;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC,CAAA;IACvE,CAAC;IAEM,SAAS;QACd,OAAO,IAAI,CAAC,IAAI,EAAE,CAAA;IACpB,CAAC;IAEM,QAAQ;QACb,OAAO,SAAS,CAAA;IAClB,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,QAAyB;IACnD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;IAEhE,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;AACrB,CAAC"}

package/dist/sleep.d.ts

@@ -0,0 +1,2 @@
+export * from './activities/SleepActivity.js';
+//# sourceMappingURL=sleep.d.ts.map

package/dist/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../src/sleep.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA"}

package/dist/sleep.js

@@ -0,0 +1,2 @@
+export * from './activities/SleepActivity.js';
+//# sourceMappingURL=sleep.js.map

package/dist/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../src/sleep.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA"}

package/dist/utils/parse-duration.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDuration(duration: number | string): number;
+//# sourceMappingURL=parse-duration.d.ts.map

package/dist/utils/parse-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-duration.d.ts","sourceRoot":"","sources":["../../src/utils/parse-duration.ts"],"names":[],"mappings":"AAiBA,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CA2B/D"}

package/dist/utils/parse-duration.js

@@ -0,0 +1,30 @@
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|millisecond|milliseconds|s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days)$/i;
+const UNIT_ENTRIES = [
+    [['ms', 'millisecond', 'milliseconds'], 1],
+    [['s', 'sec', 'secs', 'second', 'seconds'], 1_000],
+    [['m', 'min', 'mins', 'minute', 'minutes'], 60_000],
+    [['h', 'hr', 'hrs', 'hour', 'hours'], 3_600_000],
+    [['d', 'day', 'days'], 86_400_000],
+];
+const UNIT_TO_MS = new Map(UNIT_ENTRIES.flatMap(([aliases, value]) => aliases.map(alias => [alias, value])));
+export function parseDuration(duration) {
+    const isDurationInMs = typeof duration === 'number';
+    if (isDurationInMs) {
+        if (!Number.isFinite(duration) || duration < 0)
+            throw new Error(`Invalid sleep duration: ${duration}`);
+        return duration;
+    }
+    const trimmed = duration.trim();
+    if (!trimmed)
+        throw new Error('Invalid sleep duration: empty string');
+    const match = DURATION_PATTERN.exec(trimmed);
+    if (!match)
+        throw new Error(`Invalid sleep duration: ${duration}`);
+    const value = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const multiplier = UNIT_TO_MS.get(unit);
+    if (!multiplier)
+        throw new Error(`Invalid sleep duration unit: ${match[2]}`);
+    return Math.round(value * multiplier);
+}
+//# sourceMappingURL=parse-duration.js.map

package/dist/utils/parse-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-duration.js","sourceRoot":"","sources":["../../src/utils/parse-duration.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GACpB,uIAAuI,CAAA;AAEzI,MAAM,YAAY,GAAG;IACnB,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC;IAClD,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnD,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC;IAChD,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC;CACoC,CAAA;AAExE,MAAM,UAAU,GAAG,IAAI,GAAG,CACxB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CACxC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAU,CAAC,CAC9C,CACF,CAAA;AAED,MAAM,UAAU,aAAa,CAAC,QAAyB;IACrD,MAAM,cAAc,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAA;IAEnD,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAA;QAExD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;IAE/B,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAE5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAA;IAElE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAE9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAA;IAEpC,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAEvC,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAE5E,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC,CAAA;AACvC,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@t4h.framework/sleep",
+  "version": "0.0.0-experimental-20260907052843",
+  "description": "Sleep module for the T4H Framework",
+  "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/sleep",
+  "bugs": "https://github.com/tech4humans-brasil/framework/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tech4humans-brasil/framework.git",
+    "directory": "packages/sleep"
+  },
+  "license": "MIT",
+  "author": "Tech4Humans <contact@tech4h.com.br> (https://tech4h.com.br)",
+  "type": "module",
+  "exports": {
+    "types": "./dist/sleep.d.ts",
+    "import": "./dist/sleep.js"
+  },
+  "module": "./dist/sleep.js",
+  "types": "./dist/sleep.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    ".ai"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "yarn build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@t4h.framework/core": "^0.0.0-experimental-20260907052843",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@t4h.framework/core": "^0.0.0-experimental-20260907052843"
+  },
+  "packageManager": "yarn@4.12.0",
+  "engines": {
+    "node": ">=22"
+  }
+}