@neondatabase/functions 0.3.0 → 0.5.0

package/README.md

@@ -27,25 +27,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
-an accessor at `globalThis[NEON_FUNCTIONS_CONTEXT]` (a
-`Symbol.for("@neondatabase/functions/request-context")`) shaped like the providers used
-by Vercel and Next.js — a stable object exposing `get()`.
-
-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_FUNCTIONS_CONTEXT, NeonFunctionsContext, WaitUntil, runWithRequestContext, waitUntil } from "./lib/wait-until.js";
-export { NEON_FUNCTIONS_CONTEXT, 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_FUNCTIONS_CONTEXT, runWithRequestContext, waitUntil } from "./lib/wait-until.js";
-export { NEON_FUNCTIONS_CONTEXT, runWithRequestContext, waitUntil };
+import { waitUntil } from "./lib/wait-until.js";
+export { waitUntil };

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

@@ -1,33 +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` symbol under which the per-invocation context provider is
- * published. Mirrors the convention used by Vercel and Next.js.
- */
-declare const NEON_FUNCTIONS_CONTEXT: unique symbol;
-/**
- * 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.
+ * 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_FUNCTIONS_CONTEXT, 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;AAkBA;AAmDA;AAegB,KApFJ,oBAAA,GAoFyB;EAAA,SAAA,CAAA,EAnFxB,SAmFwB;;;;AAGjC;;cArES;;;;;;;;;iBAmDG,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,64 +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)`). Under the hood the per-invocation
-* context is carried by an `AsyncLocalStorage`, so concurrent invocations sharing the
-* same isolate never clobber each other's context.
-*/
-/**
-* Well-known `globalThis` symbol under which the per-invocation context provider is
-* published. Mirrors the convention used by Vercel and Next.js.
-*/
-const NEON_FUNCTIONS_CONTEXT = Symbol.for("@neondatabase/functions/request-context");
-/**
-* Holds the per-invocation context. Each `runWithRequestContext(...)` call binds a
-* fresh context for the duration of its callback (and any async work it spawns), so
-* `waitUntil` always resolves to the right invocation even under concurrency.
-*/
-const requestContextStore = new AsyncLocalStorage();
-const globalWithContext = globalThis;
-/**
-* Publish a stable provider whose `get()` reads the current store. Installed once;
-* if another copy of this module (or the host runtime) has already published a
-* provider, we leave it in place rather than clobber it.
-*/
-globalWithContext[NEON_FUNCTIONS_CONTEXT] ??= { get: () => requestContextStore.getStore() };
-/**
-* Reads the current invocation context off the `globalThis` provider, falling back to
-* an empty context when no provider is published or no invocation is in scope.
-*/
-function getContext() {
-	return globalWithContext[NEON_FUNCTIONS_CONTEXT]?.get?.() ?? {};
-}
 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.
-*/
 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_FUNCTIONS_CONTEXT, 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)`). Under the hood the per-invocation\n * context is carried by an `AsyncLocalStorage`, so concurrent invocations sharing the\n * same isolate never clobber each other's context.\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 * The accessor published on `globalThis` so consumers can read the current\n * invocation context without importing the runtime. Mirrors the provider shape\n * used by Vercel (`Symbol.for(\"@vercel/request-context\")`) and Next.js\n * (`Symbol.for(\"@next/request-context\")`): a stable object exposing `get()`.\n */\ntype RequestContextProvider = {\n\tget(): NeonFunctionsContext | undefined;\n};\n\n/**\n * Well-known `globalThis` symbol under which the per-invocation context provider is\n * published. Mirrors the convention used by Vercel and Next.js.\n */\nexport const NEON_FUNCTIONS_CONTEXT: unique symbol = Symbol.for(\n\t\"@neondatabase/functions/request-context\",\n);\n\ntype GlobalWithContext = typeof globalThis & {\n\t[NEON_FUNCTIONS_CONTEXT]?: RequestContextProvider;\n};\n\n/**\n * Holds the per-invocation context. Each `runWithRequestContext(...)` call binds a\n * fresh context for the duration of its callback (and any async work it spawns), so\n * `waitUntil` always resolves to the right invocation even under concurrency.\n */\nconst requestContextStore = new AsyncLocalStorage<NeonFunctionsContext>();\n\nconst globalWithContext: GlobalWithContext = globalThis;\n\n/**\n * Publish a stable provider whose `get()` reads the current store. Installed once;\n * if another copy of this module (or the host runtime) has already published a\n * provider, we leave it in place rather than clobber it.\n */\nglobalWithContext[NEON_FUNCTIONS_CONTEXT] ??= {\n\tget: () => requestContextStore.getStore(),\n};\n\n/**\n * Reads the current invocation context off the `globalThis` provider, falling back to\n * an empty context when no provider is published or no invocation is in scope.\n */\nfunction getContext(): NeonFunctionsContext {\n\treturn globalWithContext[NEON_FUNCTIONS_CONTEXT]?.get?.() ?? {};\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.\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":";;;;;;;;;;;;;;;AAmCA,MAAa,yBAAwC,OAAO,IAC3D,yCACD;;;;;;AAWA,MAAM,sBAAsB,IAAI,kBAAwC;AAExE,MAAM,oBAAuC;;;;;;AAO7C,kBAAkB,4BAA4B,EAC7C,WAAW,oBAAoB,SAAS,EACzC;;;;;AAMA,SAAS,aAAmC;CAC3C,OAAO,kBAAkB,uBAAuB,EAAE,MAAM,KAAK,CAAC;AAC/D;AAEA,SAAS,UAAU,OAA2C;CAC7D,OACC,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAO,MAAM,SAAS;AAExB;;;;;;;;;AAUA,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.3.0",
+  "version": "0.5.0",
   "description": "Runtime helpers for Neon Functions. Currently provides a `waitUntil` primitive for deferring async work past a response.",
   "keywords": [
     "neon",