@t4h.framework/sleep 0.3.10 → 0.3.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/.ai/skills/framework-sleep/SKILL.md +33 -29
  2. package/CHANGELOG.md +16 -0
  3. package/README.md +18 -15
  4. package/dist/activities/SleepActivity.d.ts +1 -1
  5. package/dist/utils/parse-duration.d.ts.map +1 -1
  6. package/dist/utils/parse-duration.js +6 -6
  7. package/dist/utils/parse-duration.js.map +1 -1
  8. package/package.json +4 -2
package/.ai/skills/framework-sleep/SKILL.md CHANGED
@@ -1,63 +1,67 @@
1
1
  ---
2
2
  name: framework-sleep
3
3
  description: >-
4
- Guides correct use of @t4h.framework/sleep in workflows: SleepActivity, duration
5
- parsing, and async timeout behavior. Use when implementing delays in workflows,
6
- working in packages/sleep, or testing sleep with TestWorkflowEnvironment timeout
7
- outcomes.
4
+ Guides the use of @t4h.framework/sleep to pause a T4H Framework workflow
5
+ for a duration: the sleep() function, the accepted duration strings, the
6
+ SleepActivity, and how to test a workflow that sleeps with
7
+ TestWorkflowEnvironment, mockAsync and timeout(). Use when a workflow must
8
+ wait, delay a step, back off before a retry, or send a reminder later, or
9
+ when someone asks for setTimeout, a delay or a timer in a workflow.
8
10
  ---
9
11
 
10
12
  # @t4h.framework/sleep
11
13
 
12
- Non-blocking sleep for workflows. Package path: `framework/packages/sleep`. Peer dependency: `@t4h.framework/core`.
14
+ ## Wait in a workflow
13
15
 
14
- ## Import surface
15
-
16
- ```typescript
17
- import { sleep, SleepActivity } from '@t4h.framework/sleep'
18
- ```
19
-
20
- ## Workflow usage
16
+ Call `sleep` in the workflow body and `await` it:
21
17
 
22
18
  ```typescript
23
19
  import { sleep } from '@t4h.framework/sleep'
24
20
 
25
- await sleep('30 seconds')
26
- await sleep('30 days')
27
- await sleep('30s')
28
- await sleep(5000)
21
+ await sleep('5m')
29
22
  ```
30
23
 
31
- ## Duration formats
24
+ A duration is a number of milliseconds or a string: a number, an optional
25
+ space and a unit (`500ms`, `30s`, `5m`, `2h`, `1d`, `30 days`, `1.5h`).
26
+
27
+ ## Traps
32
28
 
33
- - Number: milliseconds (`5000`)
34
- - Abbreviated: `500ms`, `30s`, `5m`, `1h`, `1d`
35
- - Full words: `30 seconds`, `2 minutes`, `1 hour`, `30 days` (singular or plural)
29
+ - Never use `setTimeout` or a busy loop in a workflow. The wait is lost on a
30
+ restart and breaks replay. `sleep` records the deadline.
31
+ - Compute the duration from the workflow input or a constant, never from
32
+ `Date.now()` or `Math.random()`.
33
+ - There are no weeks, months or combined forms such as `1h30m`. Use `'14d'` or
34
+ `'90m'`.
35
+ - An invalid, empty or negative duration throws an `Error`.
36
+ - For a recurring wait, sleep once for the full interval. Do not loop on short
37
+ sleeps.
36
38
 
37
- ## Testing
39
+ ## Test
38
40
 
39
- `sleep` schedules a `SleepActivity` (an async activity that completes via
40
- `onTimeout`). `TestWorkflowEnvironment` from `@t4h.framework/core/testing`
41
- auto-resolves timeout-based activities by default (`resolveActivityTimeouts`), so
42
- a plain `execute()` advances the clock past the sleep:
41
+ `TestWorkflowEnvironment` resolves sleep timeouts by default, so a plain
42
+ `execute()` runs past the sleep with no real wait:
43
43
 
44
44
  ```typescript
45
45
  import { TestWorkflowEnvironment } from '@t4h.framework/core/testing'
46
46
 
47
47
  const env = TestWorkflowEnvironment.create({ now: 0 })
48
48
  const output = await env.execute(workflow, input)
49
- // env.clock advances to the sleep's timeout automatically
50
49
  ```
51
50
 
52
- For explicit control, drive it with the `mockAsync()` builder and the `timeout()`
53
- outcome (which runs the activity's real `onTimeout`):
51
+ To control the sleep explicitly, mock its `SleepActivity` with the
52
+ `timeout()` outcome:
54
53
 
55
54
  ```typescript
56
55
  import { mockAsync, timeout } from '@t4h.framework/core/testing'
56
+ import { SleepActivity } from '@t4h.framework/sleep'
57
57
 
58
58
  await env.execute(workflow, input, {
59
59
  mockAsyncActivity: mockAsync().on(SleepActivity, timeout()),
60
60
  })
61
61
  ```
62
62
 
63
- See the **framework-workflow-testing** skill for the full harness API.
63
+ ## Reference
64
+
65
+ - Guide: https://tech4humans-brasil.github.io/framework/sleep/
66
+ - Workflow testing: https://tech4humans-brasil.github.io/framework/core/testing
67
+ - Types: `node_modules/@t4h.framework/sleep/dist/sleep.d.ts`
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # @t4h.framework/sleep
2
2
 
3
+ ## 0.3.12
4
+
5
+ ### Patch Changes
6
+
7
+ - [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The sleep README links to the site, and the skill keeps only the traps and the default steps. The docs list all the accepted unit names and show how to test a sleep.
8
+
9
+ ## 0.3.11
10
+
11
+ ### Patch Changes
12
+
13
+ - [#228](https://github.com/tech4humans-brasil/framework/pull/228) [`d29e1ab`](https://github.com/tech4humans-brasil/framework/commit/d29e1ab29a039b13c3e4b075472bd615566ae75e) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Uses exact types and `unknown` in place of `any`, and checks external data with guards.
14
+ - harness: the fix-issues prompt lists each sensor as `- checkTypes: PASS`. Before, it printed `- 0: [object Object]`.
15
+ - hmac: an algorithm name such as `constructor` throws `Unsupported algorithm`.
16
+ - oidc: a discovery response with no `introspection_endpoint`, or a null introspection body, throws a clear error.
17
+ - `HttpRequestActivity.toOutput` takes `HttpRequestActivityOutput` in place of `any`.
18
+
3
19
  ## 0.3.10
4
20
 
5
21
  ## 0.3.9
package/README.md CHANGED
@@ -1,27 +1,30 @@
1
1
  # @t4h.framework/sleep
2
2
 
3
- Non-blocking sleep for workflows.
3
+ Durable, non-blocking sleep for T4H Framework workflows. Use it in place of
4
+ `setTimeout`: the wait survives a restart.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ npm install @t4h.framework/sleep
10
+ ```
11
+
12
+ Peer dependency: `@t4h.framework/core`.
4
13
 
5
14
  ## Usage
6
15
 
7
16
  ```typescript
17
+ import { Workflow } from '@t4h.framework/core'
8
18
  import { sleep } from '@t4h.framework/sleep'
9
19
 
10
- await sleep('30 seconds')
11
- await sleep('30 days')
12
- await sleep('30s')
13
- await sleep('1h')
14
- await sleep(5000)
20
+ const reminder = new Workflow({ id: 'reminder' }, async () => {
21
+ await sleep('1d')
22
+ })
15
23
  ```
16
24
 
17
- ## Duration formats
18
-
19
- | Form | Examples |
20
- | ----------- | ---------------------------------------------- |
21
- | Number (ms) | `5000` |
22
- | Abbreviated | `500ms`, `30s`, `5m`, `1h`, `1d` |
23
- | Full words | `30 seconds`, `2 minutes`, `1 hour`, `30 days` |
25
+ A duration is a number of milliseconds (`5000`) or a string such as `500ms`,
26
+ `30s`, `5m`, `2h` or `30 days`.
24
27
 
25
- Singular and plural units are supported (`second` / `seconds`, `day` / `days`, etc.).
28
+ ## Documentation
26
29
 
27
- Peer dependency: `@t4h.framework/core`.
30
+ https://tech4humans-brasil.github.io/framework/sleep/
package/dist/activities/SleepActivity.d.ts CHANGED
@@ -5,7 +5,7 @@ export type SleepActivityInput = {
5
5
  export declare class SleepActivity extends AsyncActivity<readonly [duration: number | string], SleepActivityInput, void, void, SleepActivityInput, never> {
6
6
  toInput(duration: number | string): SleepActivityInput;
7
7
  bootstrap(input: SleepActivityInput): import("@t4h.framework/core").AsyncActivityResultPending<SleepActivityInput, never>;
8
- advance(): import("@t4h.framework/core").AsyncActivityResultRejected<void | import("@t4h.framework/core").Serializable>;
8
+ advance(): import("@t4h.framework/core").AsyncActivityResultRejected<import("@t4h.framework/core").SerializableOrVoid>;
9
9
  onTimeout(): import("@t4h.framework/core").AsyncActivityResultFulfilled<void | undefined>;
10
10
  toOutput(): undefined;
11
11
  }
package/dist/utils/parse-duration.d.ts.map CHANGED
@@ -1 +1 @@
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"}
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,CA4B/D"}
package/dist/utils/parse-duration.js CHANGED
@@ -11,20 +11,20 @@ export function parseDuration(duration) {
11
11
  const isDurationInMs = typeof duration === 'number';
12
12
  if (isDurationInMs) {
13
13
  if (!Number.isFinite(duration) || duration < 0)
14
- throw new Error(`Invalid sleep duration: ${duration}`);
14
+ throw new Error(`Invalid sleep duration: ${String(duration)}`);
15
15
  return duration;
16
16
  }
17
17
  const trimmed = duration.trim();
18
18
  if (!trimmed)
19
19
  throw new Error('Invalid sleep duration: empty string');
20
20
  const match = DURATION_PATTERN.exec(trimmed);
21
- if (!match)
21
+ const [, rawValue, rawUnit] = match ?? [];
22
+ if (rawValue === undefined || rawUnit === undefined)
22
23
  throw new Error(`Invalid sleep duration: ${duration}`);
23
- const value = Number(match[1]);
24
- const unit = match[2].toLowerCase();
25
- const multiplier = UNIT_TO_MS.get(unit);
24
+ const value = Number(rawValue);
25
+ const multiplier = UNIT_TO_MS.get(rawUnit.toLowerCase());
26
26
  if (!multiplier)
27
- throw new Error(`Invalid sleep duration unit: ${match[2]}`);
27
+ throw new Error(`Invalid sleep duration unit: ${rawUnit}`);
28
28
  return Math.round(value * multiplier);
29
29
  }
30
30
  //# sourceMappingURL=parse-duration.js.map
package/dist/utils/parse-duration.js.map CHANGED
@@ -1 +1 @@
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"}
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,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;QAEhE,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,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,KAAK,IAAI,EAAE,CAAA;IAEzC,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QACjD,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAA;IAExD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IAE9B,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IAExD,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAA;IAE3E,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC,CAAA;AACvC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t4h.framework/sleep",
3
- "version": "0.3.10",
3
+ "version": "0.3.12",
4
4
  "description": "Sleep module for the T4H Framework",
5
5
  "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/sleep",
6
6
  "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -26,12 +26,14 @@
26
26
  "scripts": {
27
27
  "build": "tsc --project tsconfig.build.json",
28
28
  "check-types": "tsc --noEmit",
29
+ "check-package": "publint --strict && attw --pack . --profile esm-only",
30
+ "lint": "eslint . --max-warnings 0",
29
31
  "prepublishOnly": "yarn build",
30
32
  "test": "vitest run",
31
33
  "test:watch": "vitest"
32
34
  },
33
35
  "devDependencies": {
34
- "@t4h.framework/core": "^0.19.0",
36
+ "@t4h.framework/core": "^0.21.0",
35
37
  "typescript": "^5.9.3",
36
38
  "vitest": "^4.0.18"
37
39
  },