@neondatabase/functions 0.2.0 → 0.4.0

package/README.md

@@ -13,7 +13,7 @@ npm install @neondatabase/functions
 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";
+import { waitUntil } from "@neondatabase/functions";
 
 export default {
 	async fetch(req: Request): Promise<Response> {
@@ -33,16 +33,17 @@ 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()`.
+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/v1";
+import { runWithRequestContext } from "@neondatabase/functions";
 
 runWithRequestContext({ waitUntil: realWaitUntil }, () => handler(req));
 ```

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, NeonFunctionsContext, WaitUntil, runWithRequestContext, waitUntil };
+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 };

package/dist/index.js

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

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

@@ -8,17 +8,21 @@ 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.
+ * 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_FUNCTIONS_CONTEXT: unique symbol;
+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.
  *
  * 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.
+ * 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).
  */
 declare function waitUntil(promise: Promise<unknown>): void;
 /**
@@ -29,5 +33,5 @@ declare function waitUntil(promise: Promise<unknown>): void;
  */
 declare function runWithRequestContext<T>(context: NeonFunctionsContext, fn: () => T): T;
 //#endregion
-export { NEON_FUNCTIONS_CONTEXT, NeonFunctionsContext, WaitUntil, runWithRequestContext, waitUntil };
+export { NEON_REQUEST_CONTEXT_KEY, 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":";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":";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"}

package/dist/lib/wait-until.js

@@ -5,34 +5,37 @@ import { AsyncLocalStorage } from "node:async_hooks";
 * (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.
+* 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` symbol under which the per-invocation context provider is
-* published. Mirrors the convention used by Vercel and Next.js.
+* 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_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 NEON_REQUEST_CONTEXT_KEY = "NEON_REQUEST_CONTEXT";
 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.
+* 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.
 */
-globalWithContext[NEON_FUNCTIONS_CONTEXT] ??= { get: () => requestContextStore.getStore() };
+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 the `globalThis` provider, falling back to
-* an empty context when no provider is published or no invocation is in scope.
+* 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_FUNCTIONS_CONTEXT]?.get?.() ?? {};
+	return globalWithContext["NEON_REQUEST_CONTEXT"] ?? {};
 }
 function isPromise(value) {
 	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
@@ -43,7 +46,8 @@ function isPromise(value) {
 *
 * 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.
+* 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}`);
@@ -59,6 +63,6 @@ function runWithRequestContext(context, fn) {
 	return requestContextStore.run(context, fn);
 }
 //#endregion
-export { NEON_FUNCTIONS_CONTEXT, runWithRequestContext, waitUntil };
+export { NEON_REQUEST_CONTEXT_KEY, 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 * 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` 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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neondatabase/functions",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Runtime helpers for Neon Functions. Currently provides a `waitUntil` primitive for deferring async work past a response.",
   "keywords": [
     "neon",
@@ -27,11 +27,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    },
-    "./v1": {
-      "types": "./dist/v1.d.ts",
-      "import": "./dist/v1.js",
-      "default": "./dist/v1.js"
     }
   },
   "files": [

package/dist/v1.d.ts

@@ -1,2 +0,0 @@
-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 +0,0 @@
-import { NEON_FUNCTIONS_CONTEXT, runWithRequestContext, waitUntil } from "./lib/wait-until.js";
-export { NEON_FUNCTIONS_CONTEXT, runWithRequestContext, waitUntil };