kubb-plugin-sveltekit-remote-functions 1.0.0-20260913.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iturner100
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+<div align="center">
+
+[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![License][license-src]][license-href]
+
+<h4>
+<a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">Kubb</a>
+<span> · </span>
+<a href="https://github.com/iturner100/kubb-plugin-sveltekit-remote-functions/issues" target="_blank" rel="noopener noreferrer">Report Bug</a>
+<span> · </span>
+<a href="https://github.com/iturner100/kubb-plugin-sveltekit-remote-functions/issues" target="_blank" rel="noopener noreferrer">Request Feature</a>
+</h4>
+
+</div>
+
+<br />
+
+# kubb-plugin-sveltekit-remote-functions
+
+### Generate SvelteKit remote functions with Kubb
+
+Generates [SvelteKit remote functions](https://svelte.dev/docs/kit/remote-functions) (`query`, `query.batch`, `query.live`, `command`, `form`, `prerender`) from an OpenAPI spec — one `*.remote.ts` file per operation. This plugin does not perform HTTP calls itself: it depends on [`@kubb/plugin-fetch`](https://kubb.dev/plugins/plugin-fetch) and wraps the async function that plugin already generates for each operation, swapping in SvelteKit's request-scoped `event.fetch` via a [custom transport](https://kubb.dev/plugins/plugin-fetch/guide/transport) and registering a pass-through [response interceptor](https://kubb.dev/plugins/plugin-fetch/guide/ interceptors) as an extension point for future SvelteKit-specific response handling.
+
+Every generated remote function uses the operation's [`@kubb/plugin-zod`](https://kubb.dev/plugins/plugin-zod) combined "options" schema directly as its argument schema, so this plugin has two hard configuration requirements (see [Requirements](#requirements)).
+
+## Install
+
+```sh
+pnpm add kubb-plugin-sveltekit-remote-functions @kubb/plugin-fetch @kubb/plugin-zod
+# or
+npm install kubb-plugin-sveltekit-remote-functions @kubb/plugin-fetch @kubb/plugin-zod
+# or
+bun add kubb-plugin-sveltekit-remote-functions @kubb/plugin-fetch @kubb/plugin-zod
+```
+
+## Requirements
+
+- `pluginFetch()` and `pluginZod()` must both be present in the same pipeline — hard, driver-enforced dependencies. This plugin throws a descriptive error at startup if either is missing.
+- `pluginZod({ inferred: true })` — `@kubb/plugin-zod` only generates the combined `{ body, path, query, headers }` "options" schema this plugin uses directly (as well as the per-parameter grouped schemas it's built from) when `inferred: true`.
+- `pluginFetch({ validator: { request: "zod", response: "zod" } })` — both request and response must be Zod-validated. The bare `validator: "zod"` shorthand only validates the response, which is not sufficient.
+
+When either requirement isn't met, this plugin reports a warning and skips generating any `*.remote.ts` files, without failing the rest of the Kubb run.
+
+## Usage
+
+```ts
+import { defineConfig } from "kubb/config";
+import { pluginZod } from "@kubb/plugin-zod";
+import { pluginFetch } from "@kubb/plugin-fetch";
+import { pluginSveltekitRemoteFunctions } from "kubb-plugin-sveltekit-remote-functions";
+
+export default defineConfig({
+  input: { path: "./petStore.yaml" },
+  output: { path: "./src/lib/generated", clean: true },
+  plugins: [
+    pluginZod({ inferred: true }),
+    pluginFetch({ output: { path: "./clients" }, validator: { request: "zod", response: "zod" } }),
+    pluginSveltekitRemoteFunctions(),
+  ],
+});
+```
+
+SvelteKit only allows remote-function files under `src` (not `src/lib/server`), so point this plugin's `output.path` accordingly — note the example above resolves it as a sibling of the config's own `output.path`, not `pluginFetch()`'s.
+
+## How the remote-function kind is chosen
+
+By default, the HTTP method decides the kind(s) generated for an operation:
+
+| Method                           | Generated kind(s)                                                |
+| -------------------------------- | ---------------------------------------------------------------- |
+| `GET`                            | `query`                                                          |
+| `POST`, `PUT`, `PATCH`, `DELETE` | `command` (plus `form` when `sveltekit.generateForms` is `true`) |
+
+Override this per operation with the `x-sveltekit-remote-function-type` OpenAPI vendor extension, an array of any of: `"query"`, `"query.batch"`, `"query.live"`, `"command"`, `"form"`, `"prerender"`. An explicit extension always takes precedence over `sveltekit.generateForms`.
+
+```yaml
+paths:
+  /pets/{petId}:
+    delete:
+      operationId: deletePet
+      x-sveltekit-remote-function-type: ["command"]
+```
+
+An invalid extension value (not an array, empty, or containing an unrecognized string) throws a descriptive error naming the operation and the offending value.
+
+## Naming when an operation generates more than one kind
+
+`query` and `command` are normally unsuffixed. Additional kinds get a suffix appended to the base operation name (the same camelCase name `@kubb/plugin-fetch` uses for the wrapped function):
+
+| Kind          | Suffix                                                                          |
+| ------------- | ------------------------------------------------------------------------------- |
+| `query`       | _(none, unless `command` is also generated for the same operation — see below)_ |
+| `command`     | _(none, unless `query` is also generated for the same operation — see below)_   |
+| `form`        | `Form`                                                                          |
+| `query.batch` | `Batch`                                                                         |
+| `query.live`  | `Live`                                                                          |
+| `prerender`   | _(none if the only kind, else `Prerender`)_                                     |
+
+For example, `POST /pets` with `sveltekit.generateForms: true` (`command` + `form`) generates `createPet` (a `command`) and `createPetForm` (a `form`). `query` and `command` are mutually exclusive under the default method-based resolution, so there's normally no ambiguity in leaving either bare; if an explicit `x-sveltekit-remote-function-type` override lists both together for the same operation, they fall back to their own suffix (`Query`/`Command`) instead, to avoid a duplicate export.
+
+The wrapped `@kubb/plugin-fetch` function is always imported under a `Fetch`-suffixed alias (e.g. `import { createPet as createPetFetch } from ...`), decoupled from the exported remote-function name(s), so an unsuffixed `query`/`command` export can never collide with the import of the function it wraps.
+
+## Explicit request/response typing
+
+Every generated remote function's handler is explicitly annotated with the types `@kubb/plugin-zod` infers for that operation, instead of relying only on inference from the schema value passed into `query`/`command`/`form`/`prerender`/`query.batch`/`query.live`:
+
+- The handler's input parameter(s) are typed as `<Name>OptionsSchemaType` — the combined `{ body, path, query, headers }` options type, resolved via `@kubb/plugin-zod`'s public `resolver.response.options(node)` accessor.
+- The handler's return value(s) are typed as `<Name>ResponseSchemaType` — the union of the operation's success responses, resolved via `resolver.response.response(node)` (the schema's value name) combined with `resolver.schema.type(name)`.
+
+For example:
+
+```ts
+export const createPet = command(createPetOptionsSchema, async (input: CreatePetOptionsSchemaType): Promise<CreatePetResponseSchemaType> => {
+  const { fetch } = getRequestEvent();
+  const transport = createSvelteKitTransport(fetch);
+  return createPetFetch({ ...input, transport }).unwrap();
+});
+```
+
+`query.batch` and `query.live` annotate every intermediate value too (the `inputs` array, the `results` array, and the returned per-item mapper's own parameter/return types for `query.batch`; the generator function's parameter and its `AsyncGenerator<...>` return type for `query.live`).
+
+This doesn't change runtime behavior — SvelteKit already infers these same types from the schema value — but it turns any drift between what `@kubb/plugin-zod` infers and what the wrapped `@kubb/plugin-fetch` function actually expects/returns into an immediate, readable compile error in the generated file, and makes each `.remote.ts` file self-documenting without having to trace through the schema value to see its shape.
+
+## Options
+
+This plugin's `Options` type extends `@kubb/plugin-fetch`'s own `Options` minus `validator` (`output`, `include`, `exclude`, `override`, `baseURL`, `group`, `sdk`, `resolver`), so configuring it feels the same as configuring `pluginFetch()`, plus one plugin-specific field:
+
+- `sveltekit.liveQueryPollIntervalMs?: number` — poll interval (ms) used by the generated `query.live` async generator body. Default `5000`.
+- `sveltekit.generateForms?: boolean` — controls the **default**, method-based kind resolution: when `false` (the default), `POST | PUT | PATCH | DELETE` operations generate just `command`; when `true`, they generate both `command` and `form`. Has no effect on operations that declare the `x-sveltekit-remote-function-type` extension — the extension always wins.
+
+Notes on the reused fields, since this plugin wraps `@kubb/plugin-fetch`'s functions rather than performing HTTP calls itself:
+
+- `output` — where this plugin's own `*.remote.ts` files are written; independent of the `pluginFetch()` instance's own `output`.
+- `group` — defaults to `{ type: 'tag' }` (unlike `@kubb/plugin-fetch`, which defaults to no grouping), so that two operations that share an `operationId` but live under different tags resolve to different output paths instead of silently colliding into a single file with duplicate exports. Override to `null`/`undefined` for a flat `output.path` instead, but only if you're confident every operation's `operationId` is unique across the whole spec.
+- `validator` — omitted entirely, unlike `@kubb/plugin-fetch`'s `Options`. Every remote function always validates its argument against the operation's `@kubb/plugin-zod` "options" schema; there is no "unchecked" mode. See [Requirements](#requirements).
+- `baseURL`, `sdk` — accepted for shape parity but are no-ops: the wrapped call already carries its own `baseURL`, and remote functions are always standalone exports, never a class-based SDK.
+
+## Extension points
+
+- **Custom transport** (`templates/sveltekitTransport.ts`, copied into `.kubb/sveltekitTransport.ts` next to `@kubb/plugin-fetch`'s own `.kubb/client.ts`): `createSvelteKitTransport(fetch)` builds a `Transport` that sends requests through the given `fetch` implementation — every generated remote function calls it with `getRequestEvent().fetch` so requests reuse the incoming request's credentials/origin. Copy and modify this file if you need different request-building behavior.
+
+## Known limitations
+
+- `form`'s schema is the same combined `{ body, path, query, headers }` options schema used by every other kind (not just the raw request body), since SvelteKit's `form` handler receives the parsed argument object directly and that object is exactly what the wrapped fetch call expects. Submitted form fields must therefore be named/nested to match that shape (e.g. `body.name`, `path.petId`), not just the body's own fields.
+- SvelteKit's `form()` is stricter than `command()`/`query()` about the schema's inferred shape (e.g. every boolean must be optional). Operations whose request body is modeled as a Zod `union` of several content-type variants (common for specs that declare the same body under multiple content types) can fail this stricter `form()` type-check even though `command()` for the same operation compiles fine — a pre-existing consequence of how `@kubb/plugin-zod` models those bodies, not something this plugin's schema selection introduces.
+- `query.batch` does not perform true HTTP-level batching — it satisfies SvelteKit's `(input, index) => output` batching contract by calling the wrapped operation once per input.
+- `query.live` generates a basic polling implementation (`sveltekit.liveQueryPollIntervalMs`), not push-based live data; customize the generated file for real-time use cases.
+- `prerender`'s per-operation `inputs`/`dynamic` options are not currently generated.
+
+## License
+
+[MIT](../LICENSE)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/kubb-plugin-sveltekit-remote-functions.svg
+[npm-version-href]: https://www.npmjs.com/package/kubb-plugin-sveltekit-remote-functions
+[npm-downloads-src]: https://img.shields.io/npm/dm/kubb-plugin-sveltekit-remote-functions.svg
+[npm-downloads-href]: https://www.npmjs.com/package/kubb-plugin-sveltekit-remote-functions
+[license-src]: https://img.shields.io/npm/l/kubb-plugin-sveltekit-remote-functions.svg
+[license-href]: ../LICENSE

package/dist/generators/remoteFunctionGenerator.d.ts

@@ -0,0 +1,9 @@
+import { type Generator } from "kubb/kit";
+import type { PluginSveltekitRemoteFunctions } from "../types.js";
+/**
+ * Core generator for `kubb-plugin-sveltekit-remote-functions`. For each HTTP operation, resolves
+ * the SvelteKit remote-function kind(s) it should generate (method-based, or overridden by
+ * `x-sveltekit-remote-function-type`), locates the `@kubb/plugin-fetch` function it wraps, and
+ * emits one `<operationName>.remote.ts` file per operation containing every resolved kind.
+ */
+export declare const remoteFunctionGenerator: Generator<PluginSveltekitRemoteFunctions>;

package/dist/generators/remoteFunctionGenerator.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import { ast } from "kubb/kit";
+import { resolveRemoteFunctionKinds } from "../kindResolution.js";
+import { remoteFunctionName } from "../naming.js";
+import { checkPreconditions, resolveFetchOperation, resolveZodOperation } from "../resolveOperations.js";
+/**
+ * Converts an absolute file path into a relative ESM import specifier (POSIX separators, no
+ * extension, `./`-prefixed for sibling files), computed from the importing file's own directory.
+ */
+function toImportSpecifier(fromFilePath, toFilePath) {
+    const relative = path.relative(path.dirname(fromFilePath), toFilePath);
+    const withoutExt = relative.replace(/\.[cm]?tsx?$/, "");
+    const posix = withoutExt.split(path.sep).join("/");
+    return posix.startsWith(".") ? posix : `./${posix}`;
+}
+const svelteImportByKind = {
+    query: "query",
+    "query.batch": "query",
+    "query.live": "query",
+    command: "command",
+    form: "form",
+    prerender: "prerender",
+};
+/**
+ * Builds the *.remote.ts source for one remote-function kind of an operation.
+ */
+function buildRemoteFunctionSource(options) {
+    const { kind, exportName, fetchName, argumentSchemaExpression, optionsSchemaTypeName, responseSchemaTypeName, pollIntervalMs, resultAccessor } = options;
+    switch (kind) {
+        case "query":
+        case "command":
+        case "form":
+        case "prerender":
+            return `export const ${exportName} = ${kind}(${argumentSchemaExpression}, async (input: ${optionsSchemaTypeName}): Promise<${responseSchemaTypeName}> => {
+  const { fetch } = getRequestEvent()
+  const transport = createSvelteKitTransport(fetch)
+  return ${fetchName}({ ...input, transport })${resultAccessor}
+})`;
+        case "query.batch":
+            // No true HTTP batching: each input still triggers its own call to the wrapped
+            // \`@kubb/plugin-fetch\` function, deduped only at the SvelteKit layer.
+            return `export const ${exportName} = query.batch(${argumentSchemaExpression}, async (inputs: ${optionsSchemaTypeName}[]) => {
+  const { fetch } = getRequestEvent()
+  const transport = createSvelteKitTransport(fetch)
+  const results: ${responseSchemaTypeName}[] = await Promise.all(
+    inputs.map((input: ${optionsSchemaTypeName}) => ${fetchName}({ ...input, transport })${resultAccessor}),
+  )
+  return (_input: ${optionsSchemaTypeName}, index: number): ${responseSchemaTypeName} => results[index]
+})`;
+        case "query.live":
+            // Basic polling default; true push-based live data needs bespoke server logic.
+            return `export const ${exportName} = query.live(${argumentSchemaExpression}, async function* (input: ${optionsSchemaTypeName}): AsyncGenerator<${responseSchemaTypeName}> {
+  const { fetch } = getRequestEvent()
+  const transport = createSvelteKitTransport(fetch)
+  while (true) {
+    yield await ${fetchName}({ ...input, transport })${resultAccessor}
+    await new Promise((resolve) => setTimeout(resolve, ${pollIntervalMs}))
+  }
+})`;
+    }
+}
+/**
+ * Core generator for `kubb-plugin-sveltekit-remote-functions`. For each HTTP operation, resolves
+ * the SvelteKit remote-function kind(s) it should generate (method-based, or overridden by
+ * `x-sveltekit-remote-function-type`), locates the `@kubb/plugin-fetch` function it wraps, and
+ * emits one `<operationName>.remote.ts` file per operation containing every resolved kind.
+ */
+export const remoteFunctionGenerator = {
+    name: "sveltekit-remote-functions",
+    match(node) {
+        return node.kind === "Operation" && ast.isHttpOperationNode(node);
+    },
+    operation(node, ctx) {
+        if (!ast.isHttpOperationNode(node)) {
+            return undefined;
+        }
+        const kinds = resolveRemoteFunctionKinds(node, ctx.adapter.document, ctx.plugin.options?.sveltekit?.generateForms ?? false);
+        if (kinds.length === 0) {
+            return undefined;
+        }
+        // Hard requirements: `@kubb/plugin-zod` must be configured with `inferred: true` and
+        // `@kubb/plugin-fetch` with `validator: { request: 'zod', response: 'zod' }`. Skip generating
+        // anything (with a one-time warning) rather than failing the build when either is missing.
+        if (!checkPreconditions(ctx)) {
+            return undefined;
+        }
+        const fetchOp = resolveFetchOperation(node, ctx);
+        const zodOp = resolveZodOperation(node, ctx);
+        const root = path.resolve(ctx.config.root, ctx.config.output.path);
+        const file = ctx.resolver.file({
+            name: node.operationId,
+            extname: ".remote.ts",
+            tag: node.tags[0] ?? "default",
+            path: node.path,
+            root,
+            output: ctx.options.output,
+            group: ctx.options.group ?? undefined,
+        });
+        const baseName = ctx.resolver.name(node.operationId);
+        // Import the wrapped `@kubb/plugin-fetch` function under a fixed `Fetch`-suffixed alias,
+        // decoupled from whatever the remote-function export name(s) turn out to be. `Fetch` is never
+        // one of this plugin's own kind suffixes (`Query`/`Command`/`Form`/`Batch`/`Live`/`Prerender`),
+        // so the alias can never collide with an exported remote function in the same file — e.g. a
+        // `command` kind that resolves to the unsuffixed base name would otherwise clash with an
+        // import of the same name.
+        const fetchImportAlias = `${fetchOp.name}Fetch`;
+        const svelteImports = new Set(["getRequestEvent"]);
+        for (const kind of kinds) {
+            svelteImports.add(svelteImportByKind[kind]);
+        }
+        // The combined `{ body, path, query, headers }` options schema `@kubb/plugin-zod` generates
+        // (only when `inferred: true`, guaranteed by `checkPreconditions`) is used directly, unmodified,
+        // as the argument schema for every kind, `form` included: it's exactly the shape the wrapped
+        // `@kubb/plugin-fetch` function's own `options` argument expects.
+        const optionsSchemaExpression = zodOp.optionsSchemaName;
+        const sources = [];
+        // `.unwrap()` only exists when the wrapped `pluginFetch()` instance uses its default
+        // `returnType: 'full'`. With `returnType: 'data'` the wrapped call already resolves to the
+        // bare success body directly (see `FetchOperation.returnType`'s doc comment), so calling
+        // `.unwrap()` on it would be a compile error.
+        const resultAccessor = fetchOp.returnType === "data" ? "" : ".unwrap()";
+        for (const kind of kinds) {
+            const exportName = remoteFunctionName(baseName, kind, kinds);
+            sources.push(buildRemoteFunctionSource({
+                kind,
+                exportName,
+                fetchName: fetchImportAlias,
+                argumentSchemaExpression: optionsSchemaExpression,
+                optionsSchemaTypeName: zodOp.optionsSchemaTypeName,
+                responseSchemaTypeName: zodOp.responseSchemaTypeName,
+                pollIntervalMs: ctx.options.sveltekit.liveQueryPollIntervalMs,
+                resultAccessor,
+            }));
+        }
+        const kubbDir = path.dirname(fetchOp.clientPath);
+        const sveltekitTransportPath = path.join(kubbDir, "sveltekitTransport.ts");
+        const imports = [
+            ast.factory.createImport({
+                name: Array.from(svelteImports),
+                path: "$app/server",
+            }),
+            ast.factory.createImport({
+                name: [{ propertyName: fetchOp.name, name: fetchImportAlias }],
+                path: toImportSpecifier(file.path, fetchOp.path),
+            }),
+            ast.factory.createImport({
+                name: ["createSvelteKitTransport"],
+                path: toImportSpecifier(file.path, sveltekitTransportPath),
+            }),
+            ast.factory.createImport({
+                name: [zodOp.optionsSchemaName],
+                path: toImportSpecifier(file.path, zodOp.path),
+            }),
+            ast.factory.createImport({
+                name: [zodOp.optionsSchemaTypeName, zodOp.responseSchemaTypeName],
+                path: toImportSpecifier(file.path, zodOp.path),
+                isTypeOnly: true,
+            }),
+        ];
+        const fileNode = ast.factory.createFile({
+            baseName: file.baseName,
+            path: file.path,
+            imports,
+            sources: [
+                ast.factory.createSource({
+                    nodes: sources.map((source) => ast.factory.createText(source)),
+                }),
+            ],
+            exports: [],
+        });
+        return [fileNode];
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { pluginSveltekitRemoteFunctions, default } from "./plugin.js";
+export { pluginSveltekitRemoteFunctionsName, remoteFunctionTypeExtensionKey } from "./types.js";
+export type { Options, PluginSveltekitRemoteFunctions, RemoteFunctionKind, ResolvedOptions, SveltekitOptions } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { pluginSveltekitRemoteFunctions, default } from "./plugin.js";
+export { pluginSveltekitRemoteFunctionsName, remoteFunctionTypeExtensionKey } from "./types.js";

package/dist/kindResolution.d.ts

@@ -0,0 +1,29 @@
+import type { ast } from "kubb/kit";
+import { type RemoteFunctionKind } from "./types.js";
+/**
+ * Minimal, defensive shape of the parsed OpenAPI document needed to read vendor extensions off an
+ * operation. `GeneratorContext['adapter']['document']` is typed `unknown` at the `@kubb/core`
+ * level (the concrete `Document` type lives in the adapter package, e.g. `@kubb/adapter-oas`), so
+ * this plugin reads through a loose, structurally-typed view instead of depending on the adapter
+ * package directly.
+ */
+export type LooseOpenApiDocument = {
+    paths?: Record<string, Record<string, Record<string, unknown>> | undefined>;
+};
+/**
+ * Reads the raw operation object (the `get`/`post`/... entry on a path item, including vendor
+ * extensions) for an `HttpOperationNode` out of the adapter's parsed document.
+ */
+export declare function getRawOperationObject(node: ast.HttpOperationNode, document: unknown): Record<string, unknown> | undefined;
+/**
+ * Resolves which SvelteKit remote-function kinds an operation should generate.
+ *
+ * - If the operation carries `x-sveltekit-remote-function-type`, that array is used as-is (after
+ *   validating every entry and de-duplicating) — regardless of `generateForms`.
+ * - Otherwise, the HTTP method decides: `GET` → `['query']`; `POST | PUT | PATCH | DELETE` →
+ *   `['command']`, plus `'form'` when `generateForms` is `true`.
+ *
+ * Throws a descriptive error when the extension is present but malformed (not an array, empty, or
+ * containing an unknown value), since that is almost certainly a spec authoring mistake.
+ */
+export declare function resolveRemoteFunctionKinds(node: ast.HttpOperationNode, document: unknown, generateForms: boolean): Array<RemoteFunctionKind>;

package/dist/kindResolution.js

@@ -0,0 +1,50 @@
+import { remoteFunctionTypeExtensionKey } from "./types.js";
+const allKinds = new Set(["query", "query.batch", "query.live", "command", "form", "prerender"]);
+function isRemoteFunctionKind(value) {
+    return typeof value === "string" && allKinds.has(value);
+}
+/**
+ * Reads the raw operation object (the `get`/`post`/... entry on a path item, including vendor
+ * extensions) for an `HttpOperationNode` out of the adapter's parsed document.
+ */
+export function getRawOperationObject(node, document) {
+    const doc = document;
+    const method = node.method.toLowerCase();
+    return doc?.paths?.[node.path]?.[method];
+}
+/**
+ * Resolves which SvelteKit remote-function kinds an operation should generate.
+ *
+ * - If the operation carries `x-sveltekit-remote-function-type`, that array is used as-is (after
+ *   validating every entry and de-duplicating) — regardless of `generateForms`.
+ * - Otherwise, the HTTP method decides: `GET` → `['query']`; `POST | PUT | PATCH | DELETE` →
+ *   `['command']`, plus `'form'` when `generateForms` is `true`.
+ *
+ * Throws a descriptive error when the extension is present but malformed (not an array, empty, or
+ * containing an unknown value), since that is almost certainly a spec authoring mistake.
+ */
+export function resolveRemoteFunctionKinds(node, document, generateForms) {
+    const raw = getRawOperationObject(node, document);
+    const extensionValue = raw?.[remoteFunctionTypeExtensionKey];
+    if (extensionValue !== undefined) {
+        if (!Array.isArray(extensionValue) || extensionValue.length === 0) {
+            throw new Error(`Operation "${node.operationId}" declares "${remoteFunctionTypeExtensionKey}" but its value is not a non-empty array (got: ${JSON.stringify(extensionValue)}).`);
+        }
+        const invalid = extensionValue.filter((value) => !isRemoteFunctionKind(value));
+        if (invalid.length > 0) {
+            throw new Error(`Operation "${node.operationId}" declares "${remoteFunctionTypeExtensionKey}" with unsupported value(s): ${JSON.stringify(invalid)}. Valid values are: ${Array.from(allKinds).join(", ")}.`);
+        }
+        return Array.from(new Set(extensionValue));
+    }
+    switch (node.method.toUpperCase()) {
+        case "GET":
+            return ["query"];
+        case "POST":
+        case "PUT":
+        case "PATCH":
+        case "DELETE":
+            return generateForms ? ["command", "form"] : ["command"];
+        default:
+            return [];
+    }
+}

package/dist/naming.d.ts

@@ -0,0 +1,11 @@
+import type { RemoteFunctionKind } from "./types.js";
+/**
+ * Resolves the exported identifier for one remote-function kind of an operation.
+ *
+ * @param baseName - The operation's base name, e.g. `resolver.name(operationId)` (camelCase,
+ *   matching the name `@kubb/plugin-fetch` itself would use for the wrapped function).
+ * @param kind - The remote-function kind being named.
+ * @param allKinds - Every kind generated for this operation, used to decide whether `query`,
+ *   `command`, or `prerender` need a suffix.
+ */
+export declare function remoteFunctionName(baseName: string, kind: RemoteFunctionKind, allKinds: Array<RemoteFunctionKind>): string;

package/dist/naming.js

@@ -0,0 +1,44 @@
+/**
+ * Suffix applied to the base operation name for a given remote-function kind when it isn't left
+ * bare (e.g. `POST /pets` → `command` `createPet` + `form` `createPetForm`).
+ *
+ * `query` and `command` are normally unsuffixed ("primary"): an operation's default resolution
+ * never produces both for the same operation, so there is no ambiguity in leaving either bare.
+ * They only fall back to their own suffix (`Query`/`Command`) in the rare case where an explicit
+ * `x-sveltekit-remote-function-type` override lists both together (see `remoteFunctionName`).
+ * `prerender` is unsuffixed only when it is the sole kind generated for an operation.
+ */
+const suffixByKind = {
+    query: "Query",
+    command: "Command",
+    form: "Form",
+    "query.batch": "Batch",
+    "query.live": "Live",
+    prerender: "Prerender",
+};
+/**
+ * Resolves the exported identifier for one remote-function kind of an operation.
+ *
+ * @param baseName - The operation's base name, e.g. `resolver.name(operationId)` (camelCase,
+ *   matching the name `@kubb/plugin-fetch` itself would use for the wrapped function).
+ * @param kind - The remote-function kind being named.
+ * @param allKinds - Every kind generated for this operation, used to decide whether `query`,
+ *   `command`, or `prerender` need a suffix.
+ */
+export function remoteFunctionName(baseName, kind, allKinds) {
+    // `query` and `command` are mutually exclusive under the default method-based resolution, but
+    // an explicit extension override can list both for the same operation. In that case leaving
+    // both bare would produce two identically-named exports, so only the sole survivor of the pair
+    // stays unsuffixed.
+    if (kind === "query" || kind === "command") {
+        const otherPrimaryKind = kind === "query" ? "command" : "query";
+        if (!allKinds.includes(otherPrimaryKind)) {
+            return baseName;
+        }
+        return `${baseName}${suffixByKind[kind]}`;
+    }
+    if (kind === "prerender" && allKinds.length === 1) {
+        return baseName;
+    }
+    return `${baseName}${suffixByKind[kind]}`;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,48 @@
+import { type Options, type PluginSveltekitRemoteFunctions } from "./types.js";
+/**
+ * Generates SvelteKit remote functions (`query`, `query.batch`, `query.live`, `command`, `form`,
+ * `prerender`) from an OpenAPI spec, one per operation, wrapping the async function
+ * `@kubb/plugin-fetch` already generates for that operation.
+ *
+ * The HTTP method decides which remote-function kind(s) an operation generates by default
+ * (`GET` → `query`; `POST | PUT | PATCH | DELETE` → `command`, plus `form` when
+ * `sveltekit.generateForms` is `true`), overridable per operation with the
+ * `x-sveltekit-remote-function-type` OpenAPI extension (an array of
+ * `'query' | 'query.batch' | 'query.live' | 'command' | 'form' | 'prerender'`), which always takes
+ * precedence over `sveltekit.generateForms`.
+ *
+ * Requires `pluginFetch()` and `pluginZod()` in the same pipeline (both are hard, driver-enforced
+ * dependencies). Every generated remote function uses the operation's `@kubb/plugin-zod`
+ * "options" schema directly as its argument schema, which requires two additional configuration
+ * requirements on those plugins:
+ * - `pluginZod({ inferred: true })` — `@kubb/plugin-zod` only generates the combined options
+ *   schema in that mode.
+ * - `pluginFetch({ validator: { request: 'zod', response: 'zod' } })` — both request and response
+ *   must be Zod-validated (the bare `validator: 'zod'` shorthand only validates the response).
+ *
+ * When either requirement isn't met, this plugin warns and skips generating any `*.remote.ts`
+ * files, without failing the rest of the build.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb/config'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ * import { pluginFetch } from '@kubb/plugin-fetch'
+ * import { pluginSveltekitRemoteFunctions } from 'kubb-plugin-sveltekit-remote-functions'
+ *
+ * export default defineConfig({
+ *   input: './petStore.yaml',
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     // Required by `pluginFetch()` itself (a hard dependency of its own) — not by this plugin.
+ *     pluginTs(),
+ *     pluginZod({ inferred: true }),
+ *     pluginFetch({ output: { path: './clients' }, validator: { request: 'zod', response: 'zod' } }),
+ *     pluginSveltekitRemoteFunctions({ output: { path: '../remote' } }),
+ *   ],
+ * })
+ * ```
+ */
+export declare const pluginSveltekitRemoteFunctions: (options?: Options | undefined) => import("kubb/kit").Plugin<PluginSveltekitRemoteFunctions>;
+export default pluginSveltekitRemoteFunctions;