@aventara/next 0.0.0-stage → 1.0.0-rc.9

package/dist/server-operations.factory.js

@@ -0,0 +1,123 @@
+import { AvConstructionError, } from "@aventara/core";
+import { io } from "next/cache.js";
+function ioBeforeCall() {
+    try {
+        return io();
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+const handlesBeforeBuild = (member) => `Aventara: \`${member}\` builds its handles on the Framework, which is built on first use; \`await ready()\` before building them.`;
+const CLIENT_MEMBERS = ["tx", "transaction"];
+const APPLICATION_MEMBERS = ["appTx", "transaction"];
+export function refuseMemberClashes(framework) {
+    const clashes = [
+        ...clashesOf("avClient", framework.contracts.client.resources, CLIENT_MEMBERS),
+        ...clashesOf("avApp", framework.contracts.application.resources, APPLICATION_MEMBERS),
+    ];
+    if (clashes.length > 0) {
+        throw new AvConstructionError("contract-compilation", clashes.map(({ tree, member }) => ({
+            code: "COMPILER_RESERVED_RESOURCE_NAME",
+            path: `adapter.model.resources.${member}`,
+            message: `resource "${member}" clashes with ${tree}.${member}; rename the Resource or expose it under another name`,
+        })));
+    }
+}
+function clashesOf(tree, resources, members) {
+    return members
+        .filter((member) => Object.hasOwn(resources, member))
+        .map((member) => ({ tree, member }));
+}
+export function createServerOperations(source, requestState) {
+    const withRequestState = async (options) => {
+        if (options?.state !== undefined) {
+            return options;
+        }
+        const state = await requestState();
+        return state === undefined ? options : { ...options, state };
+    };
+    const asGiven = async (options) => options;
+    const clientTransaction = transactionOf(source, withRequestState);
+    const applicationTransaction = transactionOf(source, asGiven);
+    return {
+        avClient: operationTree("avClient", source, (framework) => framework.serverClient, withRequestState, {
+            tx: () => builders(source, "avClient.tx").serverClientTx,
+            transaction: () => clientTransaction,
+        }),
+        avApp: operationTree("avApp", source, (framework) => framework.application, asGiven, {
+            appTx: () => builders(source, "avApp.appTx").appTx,
+            transaction: () => applicationTransaction,
+        }),
+    };
+}
+function builders(source, member) {
+    const framework = source.current();
+    if (framework === undefined) {
+        throw new Error(handlesBeforeBuild(member));
+    }
+    return framework;
+}
+function transactionOf(source, fill) {
+    return async (operations, options) => {
+        await ioBeforeCall();
+        const framework = await source.built();
+        return framework.transaction(operations, await fill(options));
+    };
+}
+const NEVER_A_RESOURCE = new Set(["then", "__esModule"]);
+function operationTree(name, source, layer, fill, members) {
+    const leaf = (path) => async (args, options) => {
+        await ioBeforeCall();
+        const framework = await source.built();
+        const call = memberAt(layer(framework), path);
+        if (typeof call !== "function") {
+            throw new TypeError(`${name}.${path.join(".")} is not a function`);
+        }
+        return call(args, await fill(options));
+    };
+    const resources = new Map();
+    return new Proxy(Object.freeze(Object.create(null)), {
+        get: (_target, key) => {
+            if (typeof key !== "string" || NEVER_A_RESOURCE.has(key)) {
+                return undefined;
+            }
+            const member = Object.hasOwn(members, key) ? members[key] : undefined;
+            if (member !== undefined) {
+                return member();
+            }
+            let resource = resources.get(key);
+            if (resource === undefined) {
+                resource = keyedNodes((family) => keyedNodes((variant) => leaf([key, family, variant])));
+                resources.set(key, resource);
+            }
+            return resource;
+        },
+    });
+}
+function keyedNodes(child) {
+    const children = new Map();
+    return new Proxy(Object.freeze(Object.create(null)), {
+        get: (_target, key) => {
+            if (typeof key !== "string" || NEVER_A_RESOURCE.has(key)) {
+                return undefined;
+            }
+            if (!children.has(key)) {
+                children.set(key, child(key));
+            }
+            return children.get(key);
+        },
+    });
+}
+function memberAt(root, path) {
+    let node = root;
+    for (const key of path) {
+        if (typeof node !== "object" ||
+            node === null ||
+            !Object.hasOwn(node, key)) {
+            return undefined;
+        }
+        node = node[key];
+    }
+    return node;
+}

package/dist/shared-framework.registry.d.ts

@@ -0,0 +1,25 @@
+import type { AvFramework } from "@aventara/core";
+/** One `api` path's build, shared by every copy of the module that calls `Aventara()` with the same options. */
+export type FrameworkSlot = {
+    readonly fingerprint: string;
+    /** The build: once started, kept, a construction error included. */
+    framework: Promise<AvFramework> | undefined;
+    /** The Framework once built. */
+    built: AvFramework | undefined;
+};
+/** The `globalThis` key the build for `api` is held under. */
+export declare const frameworkKey: (api: string) => symbol;
+/**
+ * The slot for `api` in this process: the one a copy of the same module
+ * already holds (the same `fingerprint`), else a new one. A different
+ * fingerprint is refused in production and replaces the slot otherwise.
+ *
+ * @throws Error when another configuration holds `api` in production.
+ */
+export declare function frameworkSlot(api: string, fingerprint: string): FrameworkSlot;
+/**
+ * The options' fingerprint: their plain data in a stable order; a function or
+ * any other object than plain data and arrays counts only as present, since
+ * bundlers spell them differently in each layer of one app.
+ */
+export declare function optionsFingerprint(options: unknown): string;

package/dist/shared-framework.registry.js

@@ -0,0 +1,65 @@
+const KEY_PREFIX = "aventara.next.framework:";
+const environment = () => globalThis.process?.env;
+export const frameworkKey = (api) => Symbol.for(`${KEY_PREFIX}${api}`);
+function claimed(api) {
+    return `Aventara: another configuration already serves the \`api\` path ${api === "" ? "/" : api} in this process; give each Aventara() its own \`api\` path.`;
+}
+export function frameworkSlot(api, fingerprint) {
+    const key = frameworkKey(api);
+    const global = globalThis;
+    const held = global[key];
+    if (held !== undefined) {
+        if (held.fingerprint === fingerprint) {
+            return held;
+        }
+        if (environment()?.NODE_ENV === "production") {
+            throw new Error(claimed(api));
+        }
+    }
+    const slot = {
+        fingerprint,
+        framework: undefined,
+        built: undefined,
+    };
+    global[key] = slot;
+    return slot;
+}
+export function optionsFingerprint(options) {
+    const seen = new Set();
+    const walk = (value) => {
+        switch (typeof value) {
+            case "function":
+                return "fn";
+            case "bigint":
+                return `${value}n`;
+            case "object":
+                break;
+            default:
+                return String(JSON.stringify(value));
+        }
+        if (value === null) {
+            return "null";
+        }
+        if (seen.has(value)) {
+            return "[cycle]";
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            let text = "[";
+            for (const member of value) {
+                text += `${walk(member)},`;
+            }
+            return `${text}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return "obj";
+        }
+        let text = "{";
+        for (const key of Object.keys(value).sort()) {
+            text += `${JSON.stringify(key)}:${walk(value[key])},`;
+        }
+        return `${text}}`;
+    };
+    return walk(options);
+}

package/dist/universal-path.registry.d.ts

@@ -0,0 +1,25 @@
+import type { StateSeed } from "./protocol-route.table.js";
+import { type ProtocolHost } from "./route-handlers.factory.js";
+/** The `globalThis` key the in-process path is registered under. */
+export declare const UNIVERSAL_PATH_KEY: unique symbol;
+/** The request the generated client's transport hands to its `fetch`. */
+export type UniversalRequest = {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+};
+/** What the generated client's transport reads of a `fetch` answer. */
+export type UniversalAnswer = {
+    readonly status: number;
+    text(): Promise<string>;
+};
+/** The in-process path: the generated client's request in, the protocol's answer out. */
+export type UniversalPath = (url: string, init: UniversalRequest) => Promise<UniversalAnswer>;
+/**
+ * The in-process path over the protocol `host` resolves to: each request is
+ * answered by the bound member its route names, with the state `state` seeds,
+ * or by the protocol's absence answer.
+ */
+export declare function universalPath(host: () => Promise<ProtocolHost>, state: StateSeed | undefined): UniversalPath;
+/** Registers `path` as this server's in-process path for `@/aventara/universal`. */
+export declare function registerUniversalPath(path: UniversalPath): void;

package/dist/universal-path.registry.js

@@ -0,0 +1,31 @@
+import { routeKey } from "./route-handlers.factory.js";
+export const UNIVERSAL_PATH_KEY = Symbol.for("aventara.next.universal");
+function outsideApi(url, api) {
+    return `Aventara: @/aventara/universal called ${url} on the server, which is not under the configured \`api\` path ${api === "" ? "/" : api}; run aventara-build --client again (npm run aventara:prepare).`;
+}
+export function universalPath(host, state) {
+    return async (url, init) => {
+        const { binding, api, routes } = await host();
+        if (url !== api && !url.startsWith(`${api}/`)) {
+            throw new Error(outsideApi(url, api));
+        }
+        const path = url.slice(api.length);
+        const request = {
+            method: init.method,
+            path,
+            headers: Object.fromEntries(new Headers(init.headers)),
+            body: { kind: "raw", content: init.body },
+        };
+        const answer = routes.get(routeKey(init.method, path));
+        const response = answer === undefined
+            ? binding.answerAbsent(request)
+            : await answer(request, state);
+        if (response === undefined) {
+            throw new Error(outsideApi(url, api));
+        }
+        return { status: response.status, text: async () => response.body };
+    };
+}
+export function registerUniversalPath(path) {
+    globalThis[UNIVERSAL_PATH_KEY] = path;
+}

package/dist/value.dehydrator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Makes data an Aventara client answered safe to pass from the server to the
+ * browser: each `Date`, `bigint`, `Uint8Array` and decimal becomes a tagged
+ * plain object, which `avHydrate` (from `@/aventara/client`) revives in the
+ * browser, a decimal as the browser client's own `AvDecimal`. Arrays and
+ * plain objects are copied with their members dehydrated; any other value is
+ * returned as it is.
+ *
+ * Give it to TanStack Query as `dehydrate(queryClient, { serializeData: avDehydrate })`,
+ * or call it on an SWR `fallback` in a Server Component.
+ *
+ * @throws TypeError for a `Date` with no wire form (invalid, or a year past four digits).
+ */
+export declare function avDehydrate(data: unknown): unknown;

package/dist/value.dehydrator.js

@@ -0,0 +1,72 @@
+import { AvProtocol } from "@aventara/core/protocol";
+import { HYDRATION_FORMAT } from "./hydration-tag.format.js";
+const { tagKey, valueKey, objectTag } = HYDRATION_FORMAT;
+const DECIMAL = new RegExp(AvProtocol.scalarFormats.decimal);
+const DATETIME = new RegExp(AvProtocol.scalarFormats.datetime);
+const tagged = (tag, wire) => ({
+    [tagKey]: tag,
+    [valueKey]: wire,
+});
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function decimalString(value) {
+    const methods = value;
+    if (typeof methods.toString !== "function" ||
+        typeof methods.toJSON !== "function") {
+        return undefined;
+    }
+    const digits = methods.toString.call(value);
+    return typeof digits === "string" &&
+        DECIMAL.test(digits) &&
+        methods.toJSON.call(value) === digits
+        ? digits
+        : undefined;
+}
+function base64Of(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function datetimeOf(date) {
+    const wire = Number.isNaN(date.getTime()) ? "" : date.toISOString();
+    if (!DATETIME.test(wire)) {
+        throw new TypeError("avDehydrate: a Date that is invalid, or whose year is not four digits, has no wire form.");
+    }
+    return wire;
+}
+function dehydratedMembers(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, member]) => [key, avDehydrate(member)]));
+}
+export function avDehydrate(data) {
+    switch (typeof data) {
+        case "bigint":
+            return tagged("bigint", data.toString(10));
+        case "object":
+            break;
+        default:
+            return data;
+    }
+    if (data === null) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((member) => avDehydrate(member));
+    }
+    if (data instanceof Date) {
+        return tagged("datetime", datetimeOf(data));
+    }
+    if (data instanceof Uint8Array) {
+        return tagged("bytes", base64Of(data));
+    }
+    if (isPlainObject(data)) {
+        return Object.hasOwn(data, tagKey)
+            ? tagged(objectTag, dehydratedMembers(data))
+            : dehydratedMembers(data);
+    }
+    const decimal = decimalString(data);
+    return decimal === undefined ? data : tagged("decimal", decimal);
+}

package/dist/web-exchange.translator.d.ts

@@ -0,0 +1,15 @@
+import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
+import type { McpRequest } from "./mcp-binding.loader.js";
+/** Zero bytes: the body of a request whose body the protocol does not read. */
+export declare const NO_BYTES: Uint8Array<ArrayBuffer>;
+/**
+ * A request URL's pathname, as the `Request` carries it: the query dropped and
+ * nothing URL-decoded.
+ */
+export declare function pathnameOf(request: Request): string;
+/** The request as the protocol reads it: path relative to the mount path, its headers, raw body. */
+export declare function protocolRequest(request: Request, path: string, content: Uint8Array): AvProtocolRequest;
+/** The request as `@aventara/mcp` reads it: absolute URL at the origin the caller used, its headers, raw body, no peer address. */
+export declare function mcpRequest(request: Request, content: Uint8Array): McpRequest;
+/** The protocol's answer as the route handler's `Response`: status, headers and body as they are. */
+export declare function webResponse(answer: AvProtocolResponse): Response;

package/dist/web-exchange.translator.js

@@ -0,0 +1,37 @@
+export const NO_BYTES = new Uint8Array();
+export function pathnameOf(request) {
+    return new URL(request.url).pathname;
+}
+export function protocolRequest(request, path, content) {
+    return {
+        method: request.method,
+        path,
+        headers: Object.fromEntries(request.headers),
+        body: { kind: "raw", content },
+    };
+}
+export function mcpRequest(request, content) {
+    return {
+        method: request.method,
+        url: calledUrl(request),
+        headers: Object.fromEntries(request.headers),
+        body: content,
+        remoteAddress: undefined,
+    };
+}
+function firstOf(request, name) {
+    const value = request.headers.get(name)?.split(",")[0]?.trim();
+    return value === undefined || value === "" ? undefined : value;
+}
+function calledUrl(request) {
+    const url = new URL(request.url);
+    const host = firstOf(request, "x-forwarded-host") ?? firstOf(request, "host");
+    const scheme = firstOf(request, "x-forwarded-proto");
+    return `${scheme ?? url.protocol.slice(0, -1)}://${host ?? url.host}${url.pathname}${url.search}`;
+}
+export function webResponse(answer) {
+    return new Response(answer.body === "" ? null : answer.body, {
+        status: answer.status,
+        headers: answer.headers,
+    });
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@aventara/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.9",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "Next.js App Router host integration for Aventara.",
+  "type": "module",
+  "engines": {
+    "node": "^22.18.0 || >=24.2.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE-ADDITIONAL-PERMISSION.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@aventara/core": "1.0.0-rc.9",
+    "server-only": "0.0.1"
+  },
+  "peerDependencies": {
+    "@aventara/mcp": "1.0.0-rc.9",
+    "next": ">=16.4 <17",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aventara/mcp": {
+      "optional": true
+    }
+  },
+  "aventara": {
+    "host": {
+      "alias": "next",
+      "label": "Next.js",
+      "framework": "next",
+      "layout": {
+        "config": "src/aventara/config",
+        "adapter": "src/aventara/adapter",
+        "generated": "src/aventara/generated",
+        "client": "src/aventara/client.ts",
+        "universal": "src/aventara/universal.ts"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@aventara/build": "1.0.0-rc.9",
+    "@aventara/client": "1.0.0-rc.9",
+    "@aventara/mcp": "1.0.0-rc.9",
+    "@aventara/testing": "1.0.0-rc.9",
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "@tanstack/react-query": "5.104.2",
+    "@types/react": "19.3.0",
+    "jsdom": "30.1.2",
+    "next": "16.4.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "swr": "2.5.1",
+    "typescript-6": "npm:typescript@6.0.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --typecheck --config ./vitest.config.mts --root .",
+    "lint": "biome lint src"
+  }
 }