ajanuw-context 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# ajanuw-context
+
+A modern, lightweight TypeScript implementation of Go's `context` pattern, designed to manage propagation of deadlines, cancellation signals, and request-scoped values across asynchronous operations.
+
+## Features
+
+- 🚀 **Go-Style Context API**: Fully models Go's structured concurrency control.
+- 📦 **Modern Bundle**: Offers built-in ESM (with tree-shaking support) and UMD targets.
+- ⏱️ **Automatic Cleanups**: Clean propagation of timeouts and manual cancellations down the context tree.
+- 🔒 **Type-Safe**: Written in TypeScript with complete auto-generated type definitions.
+
+---
+
+## Installation
+
+```bash
+# Using pnpm
+pnpm add ajanuw-context
+
+# Using npm
+npm install ajanuw-context
+
+# Using yarn
+yarn add ajanuw-context
+```
+
+---
+
+## Quick Start & Examples
+
+### 1. Basic Cancellation (`WithCancel`)
+
+Perfect for stopping pending tasks when an operation is cancelled or no longer needed.
+
+```typescript
+import { Background, WithCancel } from "ajanuw-context";
+
+// Create a cancellable context from the root Background context
+const [ctx, cancel] = WithCancel(Background);
+
+async function performTask(ctx) {
+  // Simulating an async loop
+  for (let i = 0; i < 10; i++) {
+    if (ctx.err()) {
+      console.log("Task aborted:", ctx.err().message); // "context canceled"
+      return;
+    }
+    console.log(`Processing step ${i}...`);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+}
+
+performTask(ctx);
+
+// Trigger cancellation after 1.2 seconds
+setTimeout(() => {
+  cancel();
+}, 1200);
+```
+
+### 2. Time-Bound Execution (`WithTimeout` / `WithDeadline`)
+
+Useful for preventing tasks from hanging indefinitely (e.g. HTTP requests, DB queries).
+
+```typescript
+import { Background, WithTimeout } from "ajanuw-context";
+
+const [ctx, cancel] = WithTimeout(Background, 2000); // 2-second timeout
+
+async function fetchWithContext(ctx, url) {
+  const controller = new AbortController();
+  
+  // Abort the fetch request if context gets cancelled/timed out
+  ctx.done().then(() => {
+    controller.abort();
+  });
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return await response.json();
+  } catch (error) {
+    if (ctx.err()) {
+      throw new Error(`Request timed out: ${ctx.err().message}`); // "context deadline exceeded"
+    }
+    throw error;
+  } finally {
+    // Release resources
+    cancel();
+  }
+}
+```
+
+### 3. Request-Scoped Value Propagation (`WithValue`)
+
+Pass request-specific values (like Trace ID, Auth Tokens) down the call stack.
+
+```typescript
+import { Background, WithValue } from "ajanuw-context";
+
+const TRACE_ID_KEY = Symbol("TraceID");
+
+// Attach value to the context tree
+const rootCtx = WithValue(Background, TRACE_ID_KEY, "req-123456");
+
+function handleRequest(ctx) {
+  // Retrieve value from context anywhere in the call hierarchy
+  const traceId = ctx.value(TRACE_ID_KEY);
+  console.log("Current Trace ID:", traceId); // "req-123456"
+}
+
+handleRequest(rootCtx);
+```
+
+---
+
+## API Reference
+
+### Interfaces
+
+#### `Context`
+The core interface that passes deadlines, cancellation signals, and key-value attributes.
+- **`deadline(): [Date, boolean]`**: Returns the time when work done on behalf of this context should be cancelled.
+- **`done(): Promise<void>`**: Returns a promise that resolves when work done on behalf of this context is cancelled.
+- **`err(): Error | null`**: Returns `Canceled` or `DeadlineExceeded` if the context has been cancelled. Returns `null` if the context is still active.
+- **`value<T>(key: unknown): T | null`**: Looks up a key-value pair associated with the context tree.
+
+### Core Helpers
+
+#### `Background: Context`
+Returns a non-null, empty `Context`. It is never cancelled, has no values, and has no deadline. Usually used as the root context.
+
+#### `WithCancel(parent: Context): [Context, CancelFunc]`
+Returns a copy of `parent` with a new `done` promise. The returned context's `done` promise is resolved when the returned `CancelFunc` is called or when the parent context's `done` promise is resolved, whichever happens first.
+
+#### `WithValue(parent: Context, key: unknown, val: unknown): Context`
+Returns a copy of `parent` in which the association of `key` with `val` is stored.
+
+#### `WithDeadline(parent: Context, deadline: Date): [Context, CancelFunc]`
+Returns a copy of `parent` with the deadline adjusted to be no later than `deadline`.
+
+#### `WithTimeout(parent: Context, timeoutMs: number): [Context, CancelFunc]`
+Returns `WithDeadline(parent, new Date(Date.now() + timeoutMs))`.
+
+### Error Instances
+- **`Canceled`**: An `Error` indicating the context was cancelled manually (`new Error("context canceled")`).
+- **`DeadlineExceeded`**: An `Error` indicating the context timed out (`new Error("context deadline exceeded")`).
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

package/dist/esm/context.d.ts

@@ -0,0 +1,21 @@
+import { CancelFunc, Context, ContextKey } from './interface';
+/**
+ * Background 返回一个非空的、空的 Context。它永远不会被取消，没有值，也没有截止日期。
+ */
+export declare const Background: Context;
+/**
+ * WithCancel 返回父级 Context 的副本，并带有一个新的 Done Promise。
+ */
+export declare function WithCancel(parent: Context): [Context, CancelFunc];
+/**
+ * WithValue 返回父级 Context 的副本，并带有新的键值对。
+ */
+export declare function WithValue(parent: Context, key: ContextKey, val: unknown): Context;
+/**
+ * WithDeadline 返回父级 Context 的副本，并带有截止日期。
+ */
+export declare function WithDeadline(parent: Context, deadline: Date): [Context, CancelFunc];
+/**
+ * WithTimeout 返回 WithDeadline(parent, new Date(Date.now() + timeoutMs))。
+ */
+export declare function WithTimeout(parent: Context, timeoutMs: number): [Context, CancelFunc];

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './context';
+export * from './interface';

package/dist/esm/index.js

@@ -0,0 +1,95 @@
+//#region src/interface.ts
+var e = /* @__PURE__ */ Error("context canceled"), t = /* @__PURE__ */ Error("context deadline exceeded"), n = new class {
+	deadline() {
+		return [/* @__PURE__ */ new Date(0), !1];
+	}
+	done() {
+		return new Promise(() => {});
+	}
+	err() {
+		return null;
+	}
+	value(e) {
+		return null;
+	}
+}(), r = class e {
+	constructor(t) {
+		this._err = null, this._children = /* @__PURE__ */ new Set(), this._parent = t, this._done = new Promise((e) => {
+			this._resolveDone = e;
+		}), t instanceof e && t.addChild(this), this.propagateCancel(t);
+	}
+	deadline() {
+		return this._parent.deadline();
+	}
+	done() {
+		return this._done;
+	}
+	err() {
+		return this._err;
+	}
+	value(e) {
+		return this._parent.value(e);
+	}
+	propagateCancel(e) {
+		e.done().then(() => {
+			let t = e.err();
+			t && this.cancel(!1, t);
+		});
+	}
+	cancel(t, n) {
+		if (this._err === null) {
+			this._err = n, this._resolveDone();
+			for (let e of this._children) e.cancel(!1, n);
+			this._children.clear(), t && this._parent instanceof e && this._parent.removeChild(this);
+		}
+	}
+	addChild(e) {
+		this._children.add(e);
+	}
+	removeChild(e) {
+		this._children.delete(e);
+	}
+}, i = class {
+	constructor(e, t, n) {
+		this.parent = e, this.key = t, this.val = n;
+	}
+	deadline() {
+		return this.parent.deadline();
+	}
+	done() {
+		return this.parent.done();
+	}
+	err() {
+		return this.parent.err();
+	}
+	value(e) {
+		return this.key === e ? this.val : this.parent.value(e);
+	}
+};
+function a(t) {
+	let n = new r(t);
+	return [n, () => n.cancel(!0, e)];
+}
+function o(e, t, n) {
+	if (t == null) throw Error("nil key");
+	return new i(e, t, n);
+}
+function s(n, i) {
+	let [o, s] = n.deadline();
+	if (s && o < i) return a(n);
+	let c = new r(n), l = i.getTime() - Date.now();
+	if (l <= 0) return c.cancel(!0, t), [c, () => {}];
+	let u = setTimeout(() => {
+		c.cancel(!0, t);
+	}, l);
+	return [new Proxy(c, { get(e, t, n) {
+		return t === "deadline" ? () => [i, !0] : Reflect.get(e, t, n);
+	} }), () => {
+		clearTimeout(u), c.cancel(!0, e);
+	}];
+}
+function c(e, t) {
+	return s(e, new Date(Date.now() + t));
+}
+//#endregion
+export { n as Background, e as Canceled, t as DeadlineExceeded, a as WithCancel, s as WithDeadline, c as WithTimeout, o as WithValue };

package/dist/esm/interface.d.ts

@@ -0,0 +1,43 @@
+export type ContextKey = unknown;
+/**
+ * Canceled 是当 Context 被取消时，Context.err 返回的错误内容。
+ */
+export declare const Canceled: Error;
+/**
+ * DeadlineExceeded 是当 Context 的截止日期过期时，Context.err 返回的错误内容。
+ */
+export declare const DeadlineExceeded: Error;
+/**
+ * Context 跨 API 边界传递截止日期、取消信号和其他值。
+ */
+export interface Context {
+    /**
+     * deadline 返回代表此 Context 完成的工作应被取消的时间。
+     * 未设置截止日期时，deadline 返回 [Date(0), false]。
+     * 连续调用 deadline 返回相同的结果。
+     */
+    deadline(): [Date, boolean];
+    /**
+     * done 返回一个 Promise，当代表此 Context 完成的工作应被取消时，该 Promise 将被 resolve。
+     * 如果此 Context 永远无法被取消，done 可能会返回一个永远不会 resolve 的 Promise。
+     * 连续调用 done 返回相同的值。
+     */
+    done(): Promise<void>;
+    /**
+     * 如果 done 尚未 resolve，err 返回 null。
+     * 如果 done 已 resolve，err 返回一个非空错误说明原因：
+     * 如果 Context 被取消，则返回 Canceled；
+     * 如果 Context 的截止日期过期，则返回 DeadlineExceeded。
+     * 在 err 返回非空错误后，连续调用 err 返回同一个错误。
+     */
+    err(): Error | null;
+    /**
+     * value 返回此 Context 中与 key 关联的值，如果没有与 key 关联的值，则返回 null。
+     * 使用相同的 key 连续调用 value 返回相同的结果。
+     */
+    value<T = unknown>(key: ContextKey): T | null;
+}
+/**
+ * CancelFunc 指示操作放弃其工作。
+ */
+export type CancelFunc = () => void;

package/dist/umd/context.d.ts

@@ -0,0 +1,21 @@
+import { CancelFunc, Context, ContextKey } from './interface';
+/**
+ * Background 返回一个非空的、空的 Context。它永远不会被取消，没有值，也没有截止日期。
+ */
+export declare const Background: Context;
+/**
+ * WithCancel 返回父级 Context 的副本，并带有一个新的 Done Promise。
+ */
+export declare function WithCancel(parent: Context): [Context, CancelFunc];
+/**
+ * WithValue 返回父级 Context 的副本，并带有新的键值对。
+ */
+export declare function WithValue(parent: Context, key: ContextKey, val: unknown): Context;
+/**
+ * WithDeadline 返回父级 Context 的副本，并带有截止日期。
+ */
+export declare function WithDeadline(parent: Context, deadline: Date): [Context, CancelFunc];
+/**
+ * WithTimeout 返回 WithDeadline(parent, new Date(Date.now() + timeoutMs))。
+ */
+export declare function WithTimeout(parent: Context, timeoutMs: number): [Context, CancelFunc];

package/dist/umd/index.d.ts

@@ -0,0 +1,2 @@
+export * from './context';
+export * from './interface';

package/dist/umd/index.js

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.AjanuwContext={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=Error(`context canceled`),n=Error(`context deadline exceeded`),r=new class{deadline(){return[new Date(0),!1]}done(){return new Promise(()=>{})}err(){return null}value(e){return null}},i=class e{constructor(t){this._err=null,this._children=new Set,this._parent=t,this._done=new Promise(e=>{this._resolveDone=e}),t instanceof e&&t.addChild(this),this.propagateCancel(t)}deadline(){return this._parent.deadline()}done(){return this._done}err(){return this._err}value(e){return this._parent.value(e)}propagateCancel(e){e.done().then(()=>{let t=e.err();t&&this.cancel(!1,t)})}cancel(t,n){if(this._err===null){this._err=n,this._resolveDone();for(let e of this._children)e.cancel(!1,n);this._children.clear(),t&&this._parent instanceof e&&this._parent.removeChild(this)}}addChild(e){this._children.add(e)}removeChild(e){this._children.delete(e)}},a=class{constructor(e,t,n){this.parent=e,this.key=t,this.val=n}deadline(){return this.parent.deadline()}done(){return this.parent.done()}err(){return this.parent.err()}value(e){return this.key===e?this.val:this.parent.value(e)}};function o(e){let n=new i(e);return[n,()=>n.cancel(!0,t)]}function s(e,t,n){if(t==null)throw Error(`nil key`);return new a(e,t,n)}function c(e,r){let[a,s]=e.deadline();if(s&&a<r)return o(e);let c=new i(e),l=r.getTime()-Date.now();if(l<=0)return c.cancel(!0,n),[c,()=>{}];let u=setTimeout(()=>{c.cancel(!0,n)},l);return[new Proxy(c,{get(e,t,n){return t===`deadline`?()=>[r,!0]:Reflect.get(e,t,n)}}),()=>{clearTimeout(u),c.cancel(!0,t)}]}function l(e,t){return c(e,new Date(Date.now()+t))}e.Background=r,e.Canceled=t,e.DeadlineExceeded=n,e.WithCancel=o,e.WithDeadline=c,e.WithTimeout=l,e.WithValue=s});

package/dist/umd/interface.d.ts

@@ -0,0 +1,43 @@
+export type ContextKey = unknown;
+/**
+ * Canceled 是当 Context 被取消时，Context.err 返回的错误内容。
+ */
+export declare const Canceled: Error;
+/**
+ * DeadlineExceeded 是当 Context 的截止日期过期时，Context.err 返回的错误内容。
+ */
+export declare const DeadlineExceeded: Error;
+/**
+ * Context 跨 API 边界传递截止日期、取消信号和其他值。
+ */
+export interface Context {
+    /**
+     * deadline 返回代表此 Context 完成的工作应被取消的时间。
+     * 未设置截止日期时，deadline 返回 [Date(0), false]。
+     * 连续调用 deadline 返回相同的结果。
+     */
+    deadline(): [Date, boolean];
+    /**
+     * done 返回一个 Promise，当代表此 Context 完成的工作应被取消时，该 Promise 将被 resolve。
+     * 如果此 Context 永远无法被取消，done 可能会返回一个永远不会 resolve 的 Promise。
+     * 连续调用 done 返回相同的值。
+     */
+    done(): Promise<void>;
+    /**
+     * 如果 done 尚未 resolve，err 返回 null。
+     * 如果 done 已 resolve，err 返回一个非空错误说明原因：
+     * 如果 Context 被取消，则返回 Canceled；
+     * 如果 Context 的截止日期过期，则返回 DeadlineExceeded。
+     * 在 err 返回非空错误后，连续调用 err 返回同一个错误。
+     */
+    err(): Error | null;
+    /**
+     * value 返回此 Context 中与 key 关联的值，如果没有与 key 关联的值，则返回 null。
+     * 使用相同的 key 连续调用 value 返回相同的结果。
+     */
+    value<T = unknown>(key: ContextKey): T | null;
+}
+/**
+ * CancelFunc 指示操作放弃其工作。
+ */
+export type CancelFunc = () => void;

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "ajanuw-context",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "A lightweight and robust Go-style Context implementation in TypeScript to propagate deadlines, cancellation signals, and request-scoped values.",
+	"main": "./dist/umd/index.js",
+	"module": "./dist/esm/index.js",
+	"types": "./dist/esm/index.d.ts",
+	"unpkg": "./dist/umd/index.js",
+	"jsdelivr": "./dist/umd/index.js",
+	"homepage": "https://github.com/januwA/ajanuw-context#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/januwA/ajanuw-context.git"
+	},
+	"bugs": {
+		"url": "https://github.com/januwA/ajanuw-context/issues"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/esm/index.d.ts",
+			"import": "./dist/esm/index.js",
+			"require": "./dist/umd/index.js",
+			"default": "./dist/esm/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "npm run build:esm && npm run build:umd",
+		"build:esm": "vite build",
+		"build:umd": "cross-env BUILD_UMD=true vite build",
+		"build:prod": "npm run build:esm:prod && npm run build:umd:prod",
+		"build:esm:prod": "vite build --mode production",
+		"build:umd:prod": "cross-env BUILD_UMD=true vite build --mode production",
+		"dev": "vite build --watch",
+		"preview": "vite preview",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"lint": "biome check .",
+		"format": "biome check --write .",
+		"prepare": "npm run build:prod",
+		"prepublishOnly": "npm run test:coverage && npm run build:prod"
+	},
+	"engines": {
+		"node": ">=16.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.2",
+		"@types/node": "^25.5.0",
+		"@vitest/coverage-v8": "^3.2.7",
+		"cross-env": "^7.0.3",
+		"lefthook": "^2.1.9",
+		"typescript": "^6.0.2",
+		"vite": "^8.0.3",
+		"vite-plugin-dts": "^4.5.4",
+		"vitest": "^3.0.0"
+	},
+	"keywords": [
+		"typescript",
+		"esm",
+		"javascript",
+		"context"
+	],
+	"author": {
+		"name": "januwA",
+		"url": "https://github.com/januwA"
+	},
+	"license": "MIT"
+}