@effectionx/timebox 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# Timebox
+
+Constrain any operation to complete within a certain time.
+
+---
+
+Very often you want to put a limit on how long an operation may run such as a
+`fetch()` of an external resource, or handling a web request. To do this, you
+can use the `timebox()` function. It will encapsulate the operation and either
+return its result, or a otherwise a "timeout" object indicating that it did not
+complete in the required time.
+
+```ts
+import { timebox } from "@effectionx/timebox";
+import { handleRequest } from "./handle-request";
+
+// a theoretical request handler
+export function* handler(request) {
+  // do not let the handler run for more than 10 seconds
+  let result = yield* timebox(10000, () => handleRequest(request));
+  if (result.timeout) {
+    return new Response(504, "Gateway Timeout");
+  } else {
+    return result.value;
+  }
+}
+```

package/esm/mod.d.ts

@@ -0,0 +1,69 @@
+import type { Operation } from "effection";
+/**
+ * Either a succesfully computed value, or one that took too long to complete.
+ */
+export type Timeboxed<T> = Completed<T> | Timeout;
+/**
+ * A value successfully computed within the timeout window. It has metadata about how long it
+ * took.
+ */
+export interface Completed<T> {
+    /**
+     * false: indicates that there was no timeout and that value was successfully computed
+     */
+    readonly timeout: false;
+    /**
+     * The actual value
+     */
+    readonly value: T;
+    /**
+     * The time that the operation began;
+     */
+    readonly start: DOMHighResTimeStamp;
+    /**
+     * The time that the operation succesfully returned value
+     */
+    readonly end: DOMHighResTimeStamp;
+}
+/**
+ * A value that did not compute within the alloted window.
+ */
+export interface Timeout {
+    /**
+     * true: indicates that this is a timed out result and no value is available
+     */
+    readonly timeout: true;
+    /**
+     * The time that the operation began;
+     */
+    readonly start: DOMHighResTimeStamp;
+    /**
+     * The time that the operation succesfully returned value
+     */
+    readonly end: DOMHighResTimeStamp;
+}
+/**
+ * Constrain `operation` to complete within `limitMS` milliseconds
+ *
+ * @example
+ * ```ts
+ * import { timebox } from "@effectionx/timebox";
+ * import { handleRequest } from "./handle-request";
+
+ * // a theoretical request handler
+ * export function* handler(request: Request): Operation<Response> {
+ *   // do not let the handler run for more than 10 seconds
+ *   let result = yield* timebox(10000, () => handleRequest(request));
+ *   if (result.timeout) {
+ *     return new Response(504, "Gateway Timeout");
+ *   } else {
+ *     return result.value;
+ *   }
+ * }
+ * ```
+ * @param limitMS - the maximum allowable time for `operation` to complete
+ * @param operation - the operation to attempt
+ * @returns either a completed value or a timeout
+ */
+export declare function timebox<T>(limitMS: number, operation: () => Operation<T>): Operation<Timeboxed<T>>;
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC,GAC5B,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAEzB"}

package/esm/mod.js

@@ -0,0 +1,36 @@
+import { race, sleep } from "effection";
+/**
+ * Constrain `operation` to complete within `limitMS` milliseconds
+ *
+ * @example
+ * ```ts
+ * import { timebox } from "@effectionx/timebox";
+ * import { handleRequest } from "./handle-request";
+
+ * // a theoretical request handler
+ * export function* handler(request: Request): Operation<Response> {
+ *   // do not let the handler run for more than 10 seconds
+ *   let result = yield* timebox(10000, () => handleRequest(request));
+ *   if (result.timeout) {
+ *     return new Response(504, "Gateway Timeout");
+ *   } else {
+ *     return result.value;
+ *   }
+ * }
+ * ```
+ * @param limitMS - the maximum allowable time for `operation` to complete
+ * @param operation - the operation to attempt
+ * @returns either a completed value or a timeout
+ */
+export function timebox(limitMS, operation) {
+    return race([complete(operation), deadline(limitMS)]);
+}
+function* deadline(limitMS) {
+    let start = performance.now();
+    yield* sleep(limitMS);
+    return { timeout: true, start, end: performance.now() };
+}
+function* complete(op) {
+    let start = performance.now();
+    return { timeout: false, value: yield* op(), start, end: performance.now() };
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@effectionx/timebox",
+  "version": "0.1.0",
+  "author": "engineering@frontside.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefrontside/effectionx.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/thefrontside/effectionx/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">= 16"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "effection": "^3"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,69 @@
+import type { Operation } from "effection";
+/**
+ * Either a succesfully computed value, or one that took too long to complete.
+ */
+export type Timeboxed<T> = Completed<T> | Timeout;
+/**
+ * A value successfully computed within the timeout window. It has metadata about how long it
+ * took.
+ */
+export interface Completed<T> {
+    /**
+     * false: indicates that there was no timeout and that value was successfully computed
+     */
+    readonly timeout: false;
+    /**
+     * The actual value
+     */
+    readonly value: T;
+    /**
+     * The time that the operation began;
+     */
+    readonly start: DOMHighResTimeStamp;
+    /**
+     * The time that the operation succesfully returned value
+     */
+    readonly end: DOMHighResTimeStamp;
+}
+/**
+ * A value that did not compute within the alloted window.
+ */
+export interface Timeout {
+    /**
+     * true: indicates that this is a timed out result and no value is available
+     */
+    readonly timeout: true;
+    /**
+     * The time that the operation began;
+     */
+    readonly start: DOMHighResTimeStamp;
+    /**
+     * The time that the operation succesfully returned value
+     */
+    readonly end: DOMHighResTimeStamp;
+}
+/**
+ * Constrain `operation` to complete within `limitMS` milliseconds
+ *
+ * @example
+ * ```ts
+ * import { timebox } from "@effectionx/timebox";
+ * import { handleRequest } from "./handle-request";
+
+ * // a theoretical request handler
+ * export function* handler(request: Request): Operation<Response> {
+ *   // do not let the handler run for more than 10 seconds
+ *   let result = yield* timebox(10000, () => handleRequest(request));
+ *   if (result.timeout) {
+ *     return new Response(504, "Gateway Timeout");
+ *   } else {
+ *     return result.value;
+ *   }
+ * }
+ * ```
+ * @param limitMS - the maximum allowable time for `operation` to complete
+ * @param operation - the operation to attempt
+ * @returns either a completed value or a timeout
+ */
+export declare function timebox<T>(limitMS: number, operation: () => Operation<T>): Operation<Timeboxed<T>>;
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC,GAC5B,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAEzB"}

package/script/mod.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timebox = timebox;
+const effection_1 = require("effection");
+/**
+ * Constrain `operation` to complete within `limitMS` milliseconds
+ *
+ * @example
+ * ```ts
+ * import { timebox } from "@effectionx/timebox";
+ * import { handleRequest } from "./handle-request";
+
+ * // a theoretical request handler
+ * export function* handler(request: Request): Operation<Response> {
+ *   // do not let the handler run for more than 10 seconds
+ *   let result = yield* timebox(10000, () => handleRequest(request));
+ *   if (result.timeout) {
+ *     return new Response(504, "Gateway Timeout");
+ *   } else {
+ *     return result.value;
+ *   }
+ * }
+ * ```
+ * @param limitMS - the maximum allowable time for `operation` to complete
+ * @param operation - the operation to attempt
+ * @returns either a completed value or a timeout
+ */
+function timebox(limitMS, operation) {
+    return (0, effection_1.race)([complete(operation), deadline(limitMS)]);
+}
+function* deadline(limitMS) {
+    let start = performance.now();
+    yield* (0, effection_1.sleep)(limitMS);
+    return { timeout: true, start, end: performance.now() };
+}
+function* complete(op) {
+    let start = performance.now();
+    return { timeout: false, value: yield* op(), start, end: performance.now() };
+}

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}