svetch.ts v1.0.49

🚀 Svetch.ts: Zero-Effort client/types/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) or new Response(X)
• 📛 Error Definitions => inferred from any throw statement with throw error() or throw new Error

⏬ Installation

Install the package

$ npm install svetch.ts

Run the script for first-time config & first-run

$ npx svetch.ts

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.
• 📚 Beautiful API Docs with testing.
• 📃 Can use JSDocs to add more info to the endpoint documentation.
• 🤖 Handles multiple possible responses per http code.

Sample Output

Autogenerated Docs

Autogenerated responses for each HTTP Code

API Testing in the docs (Supports Path Parameters)

🤝 Dependencies

The API Docs need 💨 Tailwind and 🌼 DaisyUI for styling (for now) get it here: DaisyUI & Tailwind

1. iconify/svelte: for the icons in the docs
2. comment-parser: for parsing comments in the API code
3. json-schema-to-zod: for converting json schema to zod
4. readline-sync: for prompting the user to select the correct response type
5. ts-morph: for parsing the typescript code
6. tsx: for parsing the typescript code
7. typescript: for parsing the typescript code
8. typescript-json-schema: for converting typescript to json schema
9. yargs: for parsing the cli arguments
10. zod: for validating the payload & response

⚙ Config

You can reeinitiate your configs anytime with npx svetch.ts init

.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
  "logLevel": 5, // logging level, 
  "filter": null // only show console alerts of this level ('debug', 'warn', 'success', 'warn')
}

🔎 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: true, // default is false, uses Zod to validate payload + response
})

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
  validate: true, // default is false, uses Zod to validate payload + response
})

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.