svetch - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #golang #android #nodejs #java #awesome #vue #security #pytorch #ios #open-source

svetch

(★ 74)

Auto-Generated typesafe client & API docs generator for your Serverless Application (Svelte First)

File Explorer

Download Latest Version (.zip)

- launch.json
- settings.json
- - +page.svelte
- schema.prisma
- - api.ts
  - client.ts
  - interfaces.ts
- - +page.server.ts
  - +page.svelte
- - core.ts
  - telemetry.ts
- - check_package.ts
  - endpoint_extractors.ts
  - import-utils.ts
  - logger.ts
  - node_utils.ts
  - openapi.ts
  - svelte-codegen.ts
  - tsoa.ts
  - unroll-types.ts
  - util.ts
  - writers.ts
- bin.ts
- generator.ts
- index.ts
- init.ts
- telemetry.json
- dependencies.ts
.eslintignore
.eslintrc.json
.gitignore
.mocharc.json
.prettierrc
.svetchrc
.svetchrc.backup
.swcrc
bin.ts
biome.json
build.config.ts
build.js
bun.lockb
example.ts
isolate-0x6a571e0-1696734-v8.log
package.json
prompt.sh
README.md
tsconfig.json

# Installation Guide

1. Get the code

git clone https://github.com/Bewinxed/svetch

Downloads the entire project code from GitHub to your computer.

cd svetch

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![npm](https://img.shields.io/npm/v/svetch.ts)](https://www.npmjs.com/package/svetch.ts)
![svetch-chan (1)](https://github.com/Bewinxed/svetch/assets/9145989/67c36f21-a21e-42f1-ba50-42f457948c46)

# 🚀 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`

```diff
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`

```json
{
  "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

```ts
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

```ts
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.