svetch.ts v2.1.46

🚀 Svetch.ts: Zero-Effort client/types/schema/OpenAPI Schema/Docs generator for your API endpoints

Typesafety, Minus the typing

👉 Check it out @ (https://svetch-dev.vercel.app/) Effortlessly generate a typesafe Fetch client for your Svelte/Sveltekit applications, complete with automatic input/output zod validation and autogenerated types & API Docs.

What is this?

Svetch automatically scans your +server.ts files in /src/routes/api (or whatever directory you specify) and generates a typesafe Fetch client that has intellisense for path, query, body parameters & all the possible responses (and errors)

🧙‍♂️ Automatic Detection

• ❓ Query Params => Detected using any declarations of url.searchParams.get
• 📂 Path Params => Detected from the file directory
• 📦 Payload Definition => inferred from const payload: X = await request.json or as X
• 💬 Response Definition => inferred from any return statement with json(X) (sveltekit utility) or new Response(X)
• 📛 Error Definitions => inferred from any throw statement with throw error() or throw new Error or return error(HTTP_CODE, error_message)

⏬ How to run

$ npx svetch.ts@latest

Make sure you have a path alias for src in your svelte.config.js

import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/kit/vite';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	// Consult https://kit.svelte.dev/docs/integrations#preprocessors
	// for more information about preprocessors
	preprocess: vitePreprocess(),
	kit: {
		// adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list.
		// If your environment is not supported or you settled on a specific environment, switch out the adapter.
		// See https://kit.svelte.dev/docs/adapters for more information about adapters.
		adapter: adapter(),
+		alias: {
+			"src": "./src",
		},
	}
};

export default config;

🌟 Advantages

• 😍 ALMOST no code changes required to your existing API code
• 🚀 Almost no learning curve, Augments a regular FETCH client with data and error along with the rest of the fetch client properties, you can use it just like a regular fetch client.
• 🔎 Intellisense for your api paths.
• ✅ Typesafety for api inputs & outputs.
• 📚 Generates an OpenAPI Schema for your API, alongside with Swagger docs.
• 📃 Can use JSDocs to add more info to the endpoint documentation (WIP)
• 🤖 Handles multiple possible responses per http code.

Autogenerated Docs

The library will generate an OpenAPI compatible schema, alongside with swagger docs, by default in /docs/+page.svelte

⚙ Config

.svetchrc

{
  "framework": "sveltekit", // currently the only option
  "input": "src/routes/api", // the directory you want the generator to traverse
  "out": "src/lib/api", // the directory to output the types & the client to
  "docs": "src/routes/docs", // where to output docs
  "tsconfig": "tsconfig.json" // your tsconfig directory
}

🔎 Detection

1. Svetch will traverse your input directory, will scan for any +server.ts with exported GET/POST/PUT/DELETE functions.
2. For each endpoint it will detect...
   1. path parameters: based on the file name, e.g. user/[user_id].ts will have a path parameter of user_id
   2. query parameters: based on any parameters instantiated like url.searchParams.get('param')
   3. body parameters: based on the type of the payload Must be assigned to a const called payload ⚠ IMPORTANT
   4. response types: will pickup any top-level return statement that is instantiated like json(xxx) or new Response(xxx) along with status code

In client code

import { Svetch } from "src/lib/api/client"; // or wherever you chose to generate the client

const svetch = new Svetch({
  baseUrl: "/api", // default is '/api'
  fetch, // default is window.fetch, pass the global fetch to it in node, etc...
  validate: false, // default is false, uses Zod to validate payload + response (ON CLIENT THIS CAN MAKE THE IMPORT SIZE HUGE)
});

await svetch
  .post("user/[user_id]", {
    path: {
      user_id: 1,
    },
    body: {
      text: foodInput,
      journalId: $journal.id,
      today: new Date(),
    },
  })
  .then((response) => {
    if (response.error) throw new Error(response.error);
    food = response.data;
    loading = false;
  })
  .catch((error) => {
    throw new Error(error);
  });

In load functions

import { Svetch } from "src/lib/api/client"; // or wherever you chose to generate the client

const svetch = new Svetch({
  baseUrl: "/api", // default is '/api'
  fetch, // pass the load function's fetch to it
});

export async function load({ fetch, session }) {
  const user = await svetch.get("user").then((response) => {
    if (response.error) throw new Error(response.error);
    return response.data;
  });
  return {
    props: {
      user,
    },
  };
}

License

This library is Free for personal use, If it's useful to you, please consider purchasing a license @ https://petrasolutions.lemonsqueezy.com/checkout/buy/19210e05-ae3c-41a0-920c-324e3083618d Redistribution/Forking is Not Allowed.