@neondatabase/functions 0.4.0 → 0.6.0

package/README.md

@@ -1,19 +1,21 @@
-# @neondatabase/functions
+# @neon/functions
 
 Runtime helpers for [Neon Functions](https://neon.com). Currently provides a `waitUntil` primitive for deferring background work past a response.
 
 ## Install
 
 ```bash
-npm install @neondatabase/functions
+npm install @neon/functions
 ```
 
+> **Requirements:** Node.js >= 20.19.
+
 ## Usage
 
 The API mirrors [`@vercel/functions`](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package): import `waitUntil` and call it directly with the promise you want to keep alive.
 
 ```ts
-import { waitUntil } from "@neondatabase/functions";
+import { waitUntil } from "@neon/functions";
 
 export default {
 	async fetch(req: Request): Promise<Response> {
@@ -27,26 +29,13 @@ export default {
 `waitUntil(promise)` forwards the promise to the Neon Functions runtime, which keeps
 the invocation alive until the promise settles (up to the 15-minute `waitUntil` limit).
 When no invocation context is in scope — local dev, tests, or any non-Neon host — it is
-a **no-op**: the promise is accepted and ignored, so the same code runs everywhere
-without branching. Passing a non-`Promise` throws a `TypeError`.
+a **no-op**: the promise is accepted and ignored (it still runs on its own, it just
+isn't tracked), so the same code runs everywhere without branching. Passing a
+non-`Promise` throws a `TypeError`.
 
 ## Runtime integration
 
-The runtime carries the per-invocation context in an `AsyncLocalStorage` and publishes
-it at `globalThis.NEON_REQUEST_CONTEXT` (the key exported as `NEON_REQUEST_CONTEXT_KEY`)
-as a getter that returns the live context object **directly** — `{ waitUntil }` during
-an invocation, `undefined` outside one. `waitUntil` reads that value straight off the
-key, so there is no `.get()` provider indirection.
-
-To make `waitUntil` resolve to a given invocation, wrap the handler with
-`runWithRequestContext`. This is intended for the Neon Functions runtime; application
-code should not need it.
-
-```ts
-import { runWithRequestContext } from "@neondatabase/functions";
-
-runWithRequestContext({ waitUntil: realWaitUntil }, () => handler(req));
-```
-
-Because the context lives in `AsyncLocalStorage`, concurrent invocations in the same
-isolate each see their own context and never clobber one another.
+The runtime publishes the active invocation context on `globalThis.NEON_REQUEST_CONTEXT`
+as a getter that returns the live context object directly — `{ waitUntil }` during an
+invocation, `undefined` outside one. `waitUntil` reads that value straight off the
+global, so there is nothing for application code to wire up.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { NEON_REQUEST_CONTEXT_KEY, NeonFunctionsContext, WaitUntil, runWithRequestContext, waitUntil } from "./lib/wait-until.js";
-export { NEON_REQUEST_CONTEXT_KEY, type NeonFunctionsContext, type WaitUntil, runWithRequestContext, waitUntil };
+import { waitUntil } from "./lib/wait-until.js";
+export { waitUntil };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { NEON_REQUEST_CONTEXT_KEY, runWithRequestContext, waitUntil } from "./lib/wait-until.js";
-export { NEON_REQUEST_CONTEXT_KEY, runWithRequestContext, waitUntil };
+import { waitUntil } from "./lib/wait-until.js";
+export { waitUntil };

package/dist/lib/wait-until.d.ts

@@ -1,37 +1,20 @@
 //#region src/lib/wait-until.d.ts
-type WaitUntil = (promise: Promise<unknown>) => void;
 /**
- * The slice of the runtime context this package reads. The runtime may attach
- * additional fields; only `waitUntil` is consumed here.
- */
-type NeonFunctionsContext = {
-  waitUntil?: WaitUntil;
-};
-/**
- * Well-known `globalThis` key under which the Neon Functions runtime publishes the
- * current invocation context. The runtime installs it as a getter that returns the
- * live context object DIRECTLY — `globalThis.NEON_REQUEST_CONTEXT` is `{ waitUntil }`
- * during an invocation and `undefined` outside one — so it is read as the context
- * itself, not via a `.get()`-style provider.
- */
-declare const NEON_REQUEST_CONTEXT_KEY = "NEON_REQUEST_CONTEXT";
-/**
- * Defers async work past the response by forwarding the promise to the Neon Functions
- * runtime, which keeps the invocation alive until the promise settles.
+ * `waitUntil(promise)` defers async work past a Neon Function's response: the runtime
+ * keeps the invocation alive until the promise settles (up to the 15-minute limit).
  *
- * The context is resolved at call time from the enclosing invocation, so this stays
- * correct under concurrency. When no invocation context is in scope (local dev, tests,
- * non-Neon hosts), this is a no-op: the promise is accepted and ignored (it still runs
- * on its own — the caller already started it — it just isn't tracked).
+ * The runtime publishes the active invocation context on `globalThis.NEON_REQUEST_CONTEXT`
+ * (a getter returning `{ waitUntil }` during an invocation, `undefined` outside one), so we
+ * read it directly. Off-platform — local dev, tests, non-Neon hosts — there is no context
+ * and this is a no-op, mirroring `@vercel/functions`: the promise the caller created still
+ * runs on its own, it just isn't tracked. Passing a non-Promise throws a `TypeError`.
  */
+declare global {
+  var NEON_REQUEST_CONTEXT: {
+    waitUntil?: (promise: Promise<unknown>) => void;
+  } | undefined;
+}
 declare function waitUntil(promise: Promise<unknown>): void;
-/**
- * Runtime entry point: binds `context` as the current invocation context for the
- * duration of `fn` (and any async work it spawns), so calls to `waitUntil` inside it
- * forward to `context.waitUntil`. Intended for the Neon Functions runtime to wrap each
- * invocation; application code should not need this.
- */
-declare function runWithRequestContext<T>(context: NeonFunctionsContext, fn: () => T): T;
 //#endregion
-export { NEON_REQUEST_CONTEXT_KEY, NeonFunctionsContext, WaitUntil, runWithRequestContext, waitUntil };
+export { waitUntil };
 //# sourceMappingURL=wait-until.d.ts.map

package/dist/lib/wait-until.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait-until.d.ts","names":[],"sources":["../../src/lib/wait-until.ts"],"mappings":";KAWY,SAAA,aAAsB;AAAlC;AAMA;AAWA;AAkDA;AAegB,KA5EJ,oBAAA,GA4EyB;EAAA,SAAA,CAAA,EA3ExB,SA2EwB;;;;AAGjC;;;;;cApES,wBAAA;;;;;;;;;;iBAkDG,SAAA,UAAmB;;;;;;;iBAenB,kCACN,gCACC,IACR"}
+{"version":3,"file":"wait-until.d.ts","names":[],"sources":["../../src/lib/wait-until.ts"],"mappings":";;;;;;AAgBmC;AAanC;;;;;;0BAb4B;;;iBAaZ,SAAA,UAAmB"}

package/dist/lib/wait-until.js

@@ -1,68 +1,12 @@
-import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/lib/wait-until.ts
-/**
-* `waitUntil` extends the lifetime of a Neon Function invocation so background work
-* (logging, cache writes, analytics, …) can finish after the response has been sent.
-*
-* The public API mirrors Vercel's `@vercel/functions`: import `waitUntil` and call it
-* directly with a promise (`waitUntil(promise)`). The active invocation context is
-* published by the runtime on `globalThis`, so it can be read without importing the
-* runtime and stays correct under concurrency.
-*/
-/**
-* Well-known `globalThis` key under which the Neon Functions runtime publishes the
-* current invocation context. The runtime installs it as a getter that returns the
-* live context object DIRECTLY — `globalThis.NEON_REQUEST_CONTEXT` is `{ waitUntil }`
-* during an invocation and `undefined` outside one — so it is read as the context
-* itself, not via a `.get()`-style provider.
-*/
-const NEON_REQUEST_CONTEXT_KEY = "NEON_REQUEST_CONTEXT";
-const globalWithContext = globalThis;
-/**
-* Backs `runWithRequestContext` for local dev and tests. When the runtime is present
-* it has already published its own accessor under the same key, so we leave that in
-* place and never publish over it.
-*/
-const requestContextStore = new AsyncLocalStorage();
-if (!("NEON_REQUEST_CONTEXT" in globalWithContext)) Object.defineProperty(globalWithContext, NEON_REQUEST_CONTEXT_KEY, {
-	configurable: true,
-	get() {
-		return requestContextStore.getStore();
-	}
-});
-/**
-* Reads the current invocation context off `globalThis.NEON_REQUEST_CONTEXT`, falling
-* back to an empty context outside an invocation (local dev, tests, non-Neon hosts).
-*/
-function getContext() {
-	return globalWithContext["NEON_REQUEST_CONTEXT"] ?? {};
-}
 function isPromise(value) {
 	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
-/**
-* Defers async work past the response by forwarding the promise to the Neon Functions
-* runtime, which keeps the invocation alive until the promise settles.
-*
-* The context is resolved at call time from the enclosing invocation, so this stays
-* correct under concurrency. When no invocation context is in scope (local dev, tests,
-* non-Neon hosts), this is a no-op: the promise is accepted and ignored (it still runs
-* on its own — the caller already started it — it just isn't tracked).
-*/
 function waitUntil(promise) {
 	if (!isPromise(promise)) throw new TypeError(`waitUntil can only be called with a Promise, got ${typeof promise}`);
-	getContext().waitUntil?.(promise);
-}
-/**
-* Runtime entry point: binds `context` as the current invocation context for the
-* duration of `fn` (and any async work it spawns), so calls to `waitUntil` inside it
-* forward to `context.waitUntil`. Intended for the Neon Functions runtime to wrap each
-* invocation; application code should not need this.
-*/
-function runWithRequestContext(context, fn) {
-	return requestContextStore.run(context, fn);
+	globalThis.NEON_REQUEST_CONTEXT?.waitUntil?.(promise);
 }
 //#endregion
-export { NEON_REQUEST_CONTEXT_KEY, runWithRequestContext, waitUntil };
+export { waitUntil };
 
 //# sourceMappingURL=wait-until.js.map

package/dist/lib/wait-until.js.map

@@ -1 +1 @@
-{"version":3,"file":"wait-until.js","names":[],"sources":["../../src/lib/wait-until.ts"],"sourcesContent":["/**\n * `waitUntil` extends the lifetime of a Neon Function invocation so background work\n * (logging, cache writes, analytics, …) can finish after the response has been sent.\n *\n * The public API mirrors Vercel's `@vercel/functions`: import `waitUntil` and call it\n * directly with a promise (`waitUntil(promise)`). The active invocation context is\n * published by the runtime on `globalThis`, so it can be read without importing the\n * runtime and stays correct under concurrency.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport type WaitUntil = (promise: Promise<unknown>) => void;\n\n/**\n * The slice of the runtime context this package reads. The runtime may attach\n * additional fields; only `waitUntil` is consumed here.\n */\nexport type NeonFunctionsContext = {\n\twaitUntil?: WaitUntil;\n};\n\n/**\n * Well-known `globalThis` key under which the Neon Functions runtime publishes the\n * current invocation context. The runtime installs it as a getter that returns the\n * live context object DIRECTLY — `globalThis.NEON_REQUEST_CONTEXT` is `{ waitUntil }`\n * during an invocation and `undefined` outside one — so it is read as the context\n * itself, not via a `.get()`-style provider.\n */\nexport const NEON_REQUEST_CONTEXT_KEY = \"NEON_REQUEST_CONTEXT\";\n\ntype GlobalWithContext = typeof globalThis & {\n\t[NEON_REQUEST_CONTEXT_KEY]?: NeonFunctionsContext;\n};\n\nconst globalWithContext: GlobalWithContext = globalThis;\n\n/**\n * Backs `runWithRequestContext` for local dev and tests. When the runtime is present\n * it has already published its own accessor under the same key, so we leave that in\n * place and never publish over it.\n */\nconst requestContextStore = new AsyncLocalStorage<NeonFunctionsContext>();\n\nif (!(NEON_REQUEST_CONTEXT_KEY in globalWithContext)) {\n\tObject.defineProperty(globalWithContext, NEON_REQUEST_CONTEXT_KEY, {\n\t\tconfigurable: true,\n\t\tget() {\n\t\t\treturn requestContextStore.getStore();\n\t\t},\n\t});\n}\n\n/**\n * Reads the current invocation context off `globalThis.NEON_REQUEST_CONTEXT`, falling\n * back to an empty context outside an invocation (local dev, tests, non-Neon hosts).\n */\nfunction getContext(): NeonFunctionsContext {\n\treturn globalWithContext[NEON_REQUEST_CONTEXT_KEY] ?? {};\n}\n\nfunction isPromise(value: unknown): value is Promise<unknown> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"then\" in value &&\n\t\ttypeof value.then === \"function\"\n\t);\n}\n\n/**\n * Defers async work past the response by forwarding the promise to the Neon Functions\n * runtime, which keeps the invocation alive until the promise settles.\n *\n * The context is resolved at call time from the enclosing invocation, so this stays\n * correct under concurrency. When no invocation context is in scope (local dev, tests,\n * non-Neon hosts), this is a no-op: the promise is accepted and ignored (it still runs\n * on its own — the caller already started it — it just isn't tracked).\n */\nexport function waitUntil(promise: Promise<unknown>): void {\n\tif (!isPromise(promise)) {\n\t\tthrow new TypeError(\n\t\t\t`waitUntil can only be called with a Promise, got ${typeof promise}`,\n\t\t);\n\t}\n\tgetContext().waitUntil?.(promise);\n}\n\n/**\n * Runtime entry point: binds `context` as the current invocation context for the\n * duration of `fn` (and any async work it spawns), so calls to `waitUntil` inside it\n * forward to `context.waitUntil`. Intended for the Neon Functions runtime to wrap each\n * invocation; application code should not need this.\n */\nexport function runWithRequestContext<T>(\n\tcontext: NeonFunctionsContext,\n\tfn: () => T,\n): T {\n\treturn requestContextStore.run(context, fn);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA4BA,MAAa,2BAA2B;AAMxC,MAAM,oBAAuC;;;;;;AAO7C,MAAM,sBAAsB,IAAI,kBAAwC;AAExE,IAAI,EAAA,0BAA8B,oBACjC,OAAO,eAAe,mBAAmB,0BAA0B;CAClE,cAAc;CACd,MAAM;EACL,OAAO,oBAAoB,SAAS;CACrC;AACD,CAAC;;;;;AAOF,SAAS,aAAmC;CAC3C,OAAO,kBAAA,2BAA+C,CAAC;AACxD;AAEA,SAAS,UAAU,OAA2C;CAC7D,OACC,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAO,MAAM,SAAS;AAExB;;;;;;;;;;AAWA,SAAgB,UAAU,SAAiC;CAC1D,IAAI,CAAC,UAAU,OAAO,GACrB,MAAM,IAAI,UACT,oDAAoD,OAAO,SAC5D;CAED,WAAW,CAAC,CAAC,YAAY,OAAO;AACjC;;;;;;;AAQA,SAAgB,sBACf,SACA,IACI;CACJ,OAAO,oBAAoB,IAAI,SAAS,EAAE;AAC3C"}
+{"version":3,"file":"wait-until.js","names":[],"sources":["../../src/lib/wait-until.ts"],"sourcesContent":["/**\n * `waitUntil(promise)` defers async work past a Neon Function's response: the runtime\n * keeps the invocation alive until the promise settles (up to the 15-minute limit).\n *\n * The runtime publishes the active invocation context on `globalThis.NEON_REQUEST_CONTEXT`\n * (a getter returning `{ waitUntil }` during an invocation, `undefined` outside one), so we\n * read it directly. Off-platform — local dev, tests, non-Neon hosts — there is no context\n * and this is a no-op, mirroring `@vercel/functions`: the promise the caller created still\n * runs on its own, it just isn't tracked. Passing a non-Promise throws a `TypeError`.\n */\n\ndeclare global {\n\t// Published by the Neon Functions runtime. Declared here (the only way to type an\n\t// augmented global) so it can be read off `globalThis` without a cast. `var` is the\n\t// required form for a global augmentation.\n\tvar NEON_REQUEST_CONTEXT:\n\t\t| { waitUntil?: (promise: Promise<unknown>) => void }\n\t\t| undefined;\n}\n\nfunction isPromise(value: unknown): value is Promise<unknown> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"then\" in value &&\n\t\ttypeof value.then === \"function\"\n\t);\n}\n\nexport function waitUntil(promise: Promise<unknown>): void {\n\tif (!isPromise(promise)) {\n\t\tthrow new TypeError(\n\t\t\t`waitUntil can only be called with a Promise, got ${typeof promise}`,\n\t\t);\n\t}\n\tglobalThis.NEON_REQUEST_CONTEXT?.waitUntil?.(promise);\n}\n"],"mappings":";AAoBA,SAAS,UAAU,OAA2C;CAC7D,OACC,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAO,MAAM,SAAS;AAExB;AAEA,SAAgB,UAAU,SAAiC;CAC1D,IAAI,CAAC,UAAU,OAAO,GACrB,MAAM,IAAI,UACT,oDAAoD,OAAO,SAC5D;CAED,WAAW,sBAAsB,YAAY,OAAO;AACrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neondatabase/functions",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Runtime helpers for Neon Functions. Currently provides a `waitUntil` primitive for deferring async work past a response.",
   "keywords": [
     "neon",
@@ -43,7 +43,7 @@
     "vitest": "^3.0.9"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "provenance": false