@prisma/compute 0.1.0-dev.2.2 → 0.1.0-dev.4.1

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 (6) hide show
  1. package/README.md +6 -6
  2. package/dist/index.d.ts +2 -2
  3. package/dist/index.js +2 -2
  4. package/dist/{scale-to-zero.d.ts → keep-awake-guard.d.ts} +23 -18
  5. package/dist/{scale-to-zero.js → keep-awake-guard.js} +16 -12
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -11,7 +11,7 @@ This works well for request-driven code, but background work outside the request
11
11
 
12
12
  `@prisma/compute` provides two utilities that signal to Prisma Compute that work is still active and the application should stay awake.
13
13
 
14
- `waitUntil` keeps the application awake until a `Promise` settles. It returns `void`, so callers should keep using the original promise for result and error handling. Pass an `AbortSignal`, usually from `AbortSignal.timeout(ms)`, as a safety bound if the promise does not settle. `waitUntil` can be called multiple times during a single request.
14
+ `waitUntil` keeps the application awake until a `Promise` settles. It returns `void`, so callers should keep using the original promise for result and error handling. Pass an `AbortSignal`, usually from `AbortSignal.timeout(ms)`, as a safety bound if the promise does not settle. The signal only releases the keep-awake guard; it does not cancel the promise. Use a timeout longer than the expected promise duration so the signal acts as a cost safety net. `waitUntil` can be called multiple times during a single request.
15
15
 
16
16
  ```ts
17
17
  import { waitUntil } from "@prisma/compute";
@@ -19,16 +19,16 @@ import { waitUntil } from "@prisma/compute";
19
19
  waitUntil(doCriticalWork(), { signal: AbortSignal.timeout(30_000) });
20
20
  ```
21
21
 
22
- `ScaleToZeroGuard` is a disposable object that keeps the application awake until the guard is released. Use it for a scoped function or block of background work. `ScaleToZeroGuard` can be created multiple times during a single request and is safe to nest. Pass an `AbortSignal`, usually from `AbortSignal.timeout(ms)`, as a safety bound if release is not reached.
22
+ `KeepAwakeGuard` is a disposable object that keeps the application awake until the guard is released. Use it for a scoped function or block of background work. `KeepAwakeGuard` can be created multiple times during a single request and is safe to nest. Pass an `AbortSignal`, usually from `AbortSignal.timeout(ms)`, as a safety bound if release is not reached. The signal releases the guard only; it does not cancel the guarded work.
23
23
 
24
24
  Read more about disposables and the `using` keyword in the [MDN resource management guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Resource_management).
25
25
 
26
26
  ```ts
27
- import { ScaleToZeroGuard } from "@prisma/compute";
27
+ import { KeepAwakeGuard } from "@prisma/compute";
28
28
 
29
29
  async function runsInBackground() {
30
30
  // guard is acquired here
31
- using guard = new ScaleToZeroGuard({ signal: AbortSignal.timeout(30_000) });
31
+ using guard = new KeepAwakeGuard({ signal: AbortSignal.timeout(30_000) });
32
32
  await doCriticalWork();
33
33
  } // guard is released here
34
34
  ```
@@ -36,10 +36,10 @@ async function runsInBackground() {
36
36
  If `using` is not available, call `.release()` manually. Always release the guard in a `finally` block so it is released even if the guarded code throws.
37
37
 
38
38
  ```ts
39
- import { ScaleToZeroGuard } from "@prisma/compute";
39
+ import { KeepAwakeGuard } from "@prisma/compute";
40
40
 
41
41
  async function runsInBackground() {
42
- const guard = new ScaleToZeroGuard({ signal: AbortSignal.timeout(30_000) });
42
+ const guard = new KeepAwakeGuard({ signal: AbortSignal.timeout(30_000) });
43
43
 
44
44
  try {
45
45
  await doCriticalWork();
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { ScaleToZeroGuard, ScaleToZeroGuardOptions, waitUntil } from "./scale-to-zero.js";
2
- export { ScaleToZeroGuard, type ScaleToZeroGuardOptions, waitUntil };
1
+ import { KeepAwakeGuard, KeepAwakeGuardOptions, waitUntil } from "./keep-awake-guard.js";
2
+ export { KeepAwakeGuard, type KeepAwakeGuardOptions, waitUntil };
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- import { ScaleToZeroGuard, waitUntil } from "./scale-to-zero.js";
2
- export { ScaleToZeroGuard, waitUntil };
1
+ import { KeepAwakeGuard, waitUntil } from "./keep-awake-guard.js";
2
+ export { KeepAwakeGuard, waitUntil };
package/dist/{scale-to-zero.d.ts → keep-awake-guard.d.ts} RENAMED
@@ -1,14 +1,15 @@
1
- //#region src/scale-to-zero.d.ts
1
+ //#region src/keep-awake-guard.d.ts
2
2
  /**
3
3
  * Options for holding a Prisma Compute sleep guard.
4
4
  */
5
- interface ScaleToZeroGuardOptions {
5
+ interface KeepAwakeGuardOptions {
6
6
  /**
7
- * Signal that releases the guard when aborted.
7
+ * Signal that releases the keep-awake guard when aborted.
8
8
  *
9
- * Use `AbortSignal.timeout(ms)` for a time bound, or pass a request or
10
- * operation signal to tie the guard to caller-owned cancellation. Passing a
11
- * signal is strongly recommended as a safety bound for dangling guards.
9
+ * The signal does not cancel the underlying promise, function, or operation.
10
+ * It only releases the guard so the application can sleep again. Use
11
+ * `AbortSignal.timeout(ms)` with a timeout longer than the expected work as a
12
+ * safety bound against dangling guards and unexpected cost.
12
13
  */
13
14
  signal?: AbortSignal;
14
15
  }
@@ -16,27 +17,28 @@ interface ScaleToZeroGuardOptions {
16
17
  * Keeps a Prisma Compute application awake for scoped async work.
17
18
  *
18
19
  * Creating a guard signals the compute runtime to stay awake. Calling
19
- * {@link ScaleToZeroGuard.release}, leaving a `using` scope, or reaching
20
+ * {@link KeepAwakeGuard.release}, leaving a `using` scope, or reaching
20
21
  * the configured abort signal releases that signal. Release is idempotent, so
21
22
  * manual release and disposal can be combined safely.
22
23
  *
23
24
  * Pass `signal` whenever possible, usually from `AbortSignal.timeout(ms)`, to
24
25
  * bound how long the guard can keep the instance awake if release is not reached.
26
+ * The signal only releases the guard; it does not cancel the guarded work.
25
27
  *
26
28
  * Outside the Prisma Compute runtime, where the sleep control endpoint is
27
29
  * unavailable, the guard is a no-op.
28
30
  *
29
31
  * @example
30
32
  * ```ts
31
- * import { ScaleToZeroGuard } from "@prisma/compute";
33
+ * import { KeepAwakeGuard } from "@prisma/compute";
32
34
  *
33
- * using guard = new ScaleToZeroGuard({ signal: AbortSignal.timeout(30_000) });
35
+ * using guard = new KeepAwakeGuard({ signal: AbortSignal.timeout(30_000) });
34
36
  * await doCriticalWork();
35
37
  * ```
36
38
  *
37
39
  * @example
38
40
  * ```ts
39
- * const guard = new ScaleToZeroGuard();
41
+ * const guard = new KeepAwakeGuard();
40
42
  * try {
41
43
  * await doCriticalWork();
42
44
  * } finally {
@@ -44,16 +46,17 @@ interface ScaleToZeroGuardOptions {
44
46
  * }
45
47
  * ```
46
48
  */
47
- declare class ScaleToZeroGuard implements Disposable {
49
+ declare class KeepAwakeGuard implements Disposable {
48
50
  #private;
49
51
  /**
50
52
  * Creates a guard and immediately signals the compute runtime to stay awake.
51
53
  *
52
54
  * If `signal` is already aborted, no signal is written. If `signal` aborts
53
- * while the guard is active, the guard releases itself. Passing a signal is
54
- * recommended as a safety bound if release is not reached.
55
+ * while the guard is active, the guard releases itself without cancelling the
56
+ * guarded work. Passing a signal is recommended as a safety bound if release
57
+ * is not reached.
55
58
  */
56
- constructor(options?: ScaleToZeroGuardOptions);
59
+ constructor(options?: KeepAwakeGuardOptions);
57
60
  /**
58
61
  * Releases the guard's keep-awake signal.
59
62
  *
@@ -65,7 +68,7 @@ declare class ScaleToZeroGuard implements Disposable {
65
68
  * Releases the guard when used with TypeScript's `using` syntax.
66
69
  *
67
70
  * Most callers should prefer `using` for scoped work and call
68
- * {@link ScaleToZeroGuard.release} only when release needs to happen before
71
+ * {@link KeepAwakeGuard.release} only when release needs to happen before
69
72
  * the scope exits.
70
73
  */
71
74
  [Symbol.dispose](): void;
@@ -79,7 +82,9 @@ declare class ScaleToZeroGuard implements Disposable {
79
82
  * only the guard is released; the passed promise continues independently.
80
83
  *
81
84
  * Pass `signal`, usually from `AbortSignal.timeout(ms)`, to bound guard lifetime
82
- * even when the promise does not settle.
85
+ * even when the promise does not settle. Use a timeout longer than the expected
86
+ * promise duration: the signal is a safety net for releasing the keep-awake
87
+ * guard, not a way to cancel or interrupt the promise.
83
88
  *
84
89
  * @example
85
90
  * ```ts
@@ -88,6 +93,6 @@ declare class ScaleToZeroGuard implements Disposable {
88
93
  * waitUntil(sendWebhook(), { signal: AbortSignal.timeout(10_000) });
89
94
  * ```
90
95
  */
91
- declare function waitUntil(promise: PromiseLike<unknown>, options?: ScaleToZeroGuardOptions): void;
96
+ declare function waitUntil(promise: PromiseLike<unknown>, options?: KeepAwakeGuardOptions): void;
92
97
  //#endregion
93
- export { ScaleToZeroGuard, ScaleToZeroGuardOptions, waitUntil };
98
+ export { KeepAwakeGuard, KeepAwakeGuardOptions, waitUntil };
package/dist/{scale-to-zero.js → keep-awake-guard.js} RENAMED
@@ -1,30 +1,31 @@
1
1
  import { writeScaleToZeroSignal } from "./scale-to-zero-control.js";
2
- //#region src/scale-to-zero.ts
2
+ //#region src/keep-awake-guard.ts
3
3
  /**
4
4
  * Keeps a Prisma Compute application awake for scoped async work.
5
5
  *
6
6
  * Creating a guard signals the compute runtime to stay awake. Calling
7
- * {@link ScaleToZeroGuard.release}, leaving a `using` scope, or reaching
7
+ * {@link KeepAwakeGuard.release}, leaving a `using` scope, or reaching
8
8
  * the configured abort signal releases that signal. Release is idempotent, so
9
9
  * manual release and disposal can be combined safely.
10
10
  *
11
11
  * Pass `signal` whenever possible, usually from `AbortSignal.timeout(ms)`, to
12
12
  * bound how long the guard can keep the instance awake if release is not reached.
13
+ * The signal only releases the guard; it does not cancel the guarded work.
13
14
  *
14
15
  * Outside the Prisma Compute runtime, where the sleep control endpoint is
15
16
  * unavailable, the guard is a no-op.
16
17
  *
17
18
  * @example
18
19
  * ```ts
19
- * import { ScaleToZeroGuard } from "@prisma/compute";
20
+ * import { KeepAwakeGuard } from "@prisma/compute";
20
21
  *
21
- * using guard = new ScaleToZeroGuard({ signal: AbortSignal.timeout(30_000) });
22
+ * using guard = new KeepAwakeGuard({ signal: AbortSignal.timeout(30_000) });
22
23
  * await doCriticalWork();
23
24
  * ```
24
25
  *
25
26
  * @example
26
27
  * ```ts
27
- * const guard = new ScaleToZeroGuard();
28
+ * const guard = new KeepAwakeGuard();
28
29
  * try {
29
30
  * await doCriticalWork();
30
31
  * } finally {
@@ -32,7 +33,7 @@ import { writeScaleToZeroSignal } from "./scale-to-zero-control.js";
32
33
  * }
33
34
  * ```
34
35
  */
35
- var ScaleToZeroGuard = class {
36
+ var KeepAwakeGuard = class {
36
37
  #active;
37
38
  #abortSignal;
38
39
  #abortListener;
@@ -40,8 +41,9 @@ var ScaleToZeroGuard = class {
40
41
  * Creates a guard and immediately signals the compute runtime to stay awake.
41
42
  *
42
43
  * If `signal` is already aborted, no signal is written. If `signal` aborts
43
- * while the guard is active, the guard releases itself. Passing a signal is
44
- * recommended as a safety bound if release is not reached.
44
+ * while the guard is active, the guard releases itself without cancelling the
45
+ * guarded work. Passing a signal is recommended as a safety bound if release
46
+ * is not reached.
45
47
  */
46
48
  constructor(options = {}) {
47
49
  if (options.signal?.aborted) {
@@ -73,7 +75,7 @@ var ScaleToZeroGuard = class {
73
75
  * Releases the guard when used with TypeScript's `using` syntax.
74
76
  *
75
77
  * Most callers should prefer `using` for scoped work and call
76
- * {@link ScaleToZeroGuard.release} only when release needs to happen before
78
+ * {@link KeepAwakeGuard.release} only when release needs to happen before
77
79
  * the scope exits.
78
80
  */
79
81
  [Symbol.dispose]() {
@@ -95,7 +97,9 @@ var ScaleToZeroGuard = class {
95
97
  * only the guard is released; the passed promise continues independently.
96
98
  *
97
99
  * Pass `signal`, usually from `AbortSignal.timeout(ms)`, to bound guard lifetime
98
- * even when the promise does not settle.
100
+ * even when the promise does not settle. Use a timeout longer than the expected
101
+ * promise duration: the signal is a safety net for releasing the keep-awake
102
+ * guard, not a way to cancel or interrupt the promise.
99
103
  *
100
104
  * @example
101
105
  * ```ts
@@ -105,7 +109,7 @@ var ScaleToZeroGuard = class {
105
109
  * ```
106
110
  */
107
111
  function waitUntil(promise, options) {
108
- const guard = new ScaleToZeroGuard(options);
112
+ const guard = new KeepAwakeGuard(options);
109
113
  Promise.resolve(promise).finally(() => {
110
114
  try {
111
115
  guard.release();
@@ -113,4 +117,4 @@ function waitUntil(promise, options) {
113
117
  });
114
118
  }
115
119
  //#endregion
116
- export { ScaleToZeroGuard, waitUntil };
120
+ export { KeepAwakeGuard, waitUntil };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@prisma/compute",
3
- "version": "0.1.0-dev.2.2",
3
+ "version": "0.1.0-dev.4.1",
4
4
  "description": "Utilities for applications running on the Prisma compute runtime.",
5
5
  "type": "module",
6
6
  "exports": {