@neondatabase/functions 0.1.2 → 0.2.0

package/README.md

@@ -10,19 +10,42 @@ npm install @neondatabase/functions
 
 ## 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/v1";
 
 export default {
 	async fetch(req: Request): Promise<Response> {
-		const defer = waitUntil();
 		// Fire-and-forget background work that should outlive the response.
-		defer(logRequest(req));
+		waitUntil(logRequest(req));
 		return new Response("ok");
 	},
 };
 ```
 
-> **Status: not implemented yet.** `waitUntil()` currently returns a no-op function — the
-> promise you pass is accepted and ignored. Once the Neon Functions runtime ships, it will
-> register the promise with the host so the invocation stays alive until it settles.
+`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`.
+
+## 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/v1";
+
+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.

package/dist/index.d.ts

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

package/dist/index.js

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

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

@@ -1,20 +1,33 @@
 //#region src/lib/wait-until.d.ts
+type WaitUntil = (promise: Promise<unknown>) => void;
 /**
- * `waitUntil` extends the lifetime of a Neon Function invocation so background work
- * (logging, cache writes, analytics, …) can finish after the response has been sent.
- *
- * It mirrors the platform primitive exposed by Cloudflare Workers / Vercel
- * (`ctx.waitUntil(promise)`).
+ * The slice of the runtime context this package reads. The runtime may attach
+ * additional fields; only `waitUntil` is consumed here.
  */
-type WaitUntil = (promise: Promise<unknown>) => void;
+type NeonFunctionsContext = {
+  waitUntil?: WaitUntil;
+};
 /**
- * Returns a `waitUntil` function for the current invocation.
+ * 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.
  *
- * NOT IMPLEMENTED YET: this is a no-op placeholder. The returned function accepts a
- * promise and ignores it. Once the Neon Functions runtime ships, this will register the
- * promise with the host so the invocation stays alive until it 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.
+ */
+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 waitUntil(): WaitUntil;
+declare function runWithRequestContext<T>(context: NeonFunctionsContext, fn: () => T): T;
 //#endregion
-export { WaitUntil, waitUntil };
+export { NEON_FUNCTIONS_CONTEXT, NeonFunctionsContext, WaitUntil, runWithRequestContext, 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":";;AAOA;AASA;;;;;KATY,SAAA,aAAsB;;;;;;;;iBASlB,SAAA,CAAA,GAAa"}
+{"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"}

package/dist/lib/wait-until.js

@@ -1,15 +1,64 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/lib/wait-until.ts
 /**
-* Returns a `waitUntil` function for the current invocation.
+* `waitUntil` extends the lifetime of a Neon Function invocation so background work
+* (logging, cache writes, analytics, …) can finish after the response has been sent.
 *
-* NOT IMPLEMENTED YET: this is a no-op placeholder. The returned function accepts a
-* promise and ignores it. Once the Neon Functions runtime ships, this will register the
-* promise with the host so the invocation stays alive until it settles.
+* 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.
 */
-function waitUntil() {
-	return (_promise) => {};
+/**
+* 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);
 }
 //#endregion
-export { waitUntil };
+export { NEON_FUNCTIONS_CONTEXT, runWithRequestContext, 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 * It mirrors the platform primitive exposed by Cloudflare Workers / Vercel\n * (`ctx.waitUntil(promise)`).\n */\nexport type WaitUntil = (promise: Promise<unknown>) => void;\n\n/**\n * Returns a `waitUntil` function for the current invocation.\n *\n * NOT IMPLEMENTED YET: this is a no-op placeholder. The returned function accepts a\n * promise and ignores it. Once the Neon Functions runtime ships, this will register the\n * promise with the host so the invocation stays alive until it settles.\n */\nexport function waitUntil(): WaitUntil {\n\treturn (_promise: Promise<unknown>): void => {\n\t\t// no-op: the runtime integration is not implemented yet.\n\t};\n}\n"],"mappings":";;;;;;;;AAgBA,SAAgB,YAAuB;CACtC,QAAQ,aAAqC,CAE7C;AACD"}
+{"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"}

package/dist/v1.d.ts

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

package/dist/v1.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neondatabase/functions",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Runtime helpers for Neon Functions. Currently provides a `waitUntil` primitive for deferring async work past a response.",
   "keywords": [
     "neon",