TSDL core utils and types

@tsdl/bun, @tsdl/client, @tsdl/core, @tsdl/dashboard, @tsdl/express, @tsdl/gui, @tsdl/node, @tsdl/react-query, @tsdl/server, @tsdl/tree

TSDL, short for Type-Safe Data Layer, is a transport layer designed to blur the line between client and server side. TSDL is an end-to-end http communication framework that makes your backend a type-safe library for your frontend.

👉 Installation

Example code

Server side

const router = tsdl.router({
   auth: tsdl.router({
      login: tsdl // ✓ structured and nestable routes, easily refactored
         .use(logger) // ✓ reusable and powerful middleware support
         .use(cors)
         .input(loginSchema) // ✓ Zod, Ajv, Joi, Yup etc. or custom
         .query(async ({ input }) => {
            input.username // ✓ type inferred and input schema validated
            const user = await db.findOne({
               where: { username: input.username }
            });

            if (!user) {
               // ✓ consistent and simple error handling
               throw new TSDLError(404, "oops");
            }
            // ✓ return any JS value to the client
            return user;
         }),
   }),
});

Client side

const onSubmit = async () => {
   try {
      const result = await tsdl.auth.login({
         username: form.username, // ✓ write with confidence, inputs are type safe
      });

      // ✓ correctly inferred JSON serialized type
      console.log(result);
   } catch(e) {
      // (e is unknown by default, this is just for type inference)
      if (e instanceof TSDLError) {
         // ✓ handle errors with confidence and consistency
         console.log(e.message); // "oops"
         console.log(e.code); // "Not Found"
         console.log(e.numberCode); // 404
      }
   }
}

Ready to dive in? Getting started guide

Links

• Documentation
• Installation
• Server setup
• Client setup

Features

Replaces

• ~~Rest APIs~~
• ~~Express/Koa/Nest etc.~~
• ~~GraphQL~~

Introduces

• Type-safe back-end architecture
• Incrementally adoptable — works alongside existing Node infrastructure
• Express.js support @tsdl/express
• Built-in documentation
• Generate un-opinionated AST of (documented) back-end @tsdl/tree
• Type-safe and implicit input validation
• Type-safe and powerful middleware
• Modular API (install only what you need)
• TanStack Query (FKA React Query) and SWR integration @tsdl/react-query
• Consistent error handling
• And more...

Contributing

TSDL is developed as a monorepo using Nx for cloud runs and caching as well as Lerna for package linking and publishing.

1. Clone the repository

   git clone https://github.com/asplunds/tsdl.git tsdl

2. Install dependencies (also initializes husky, & symlinks packages)

   npm i

3. Start hacking! Unit tests are located in /tests. For playing, use /playground (it's git ignored but included in workspaces). You can find examples in /examples.

Docs (nextra)

1. cd meta/docs
2. npm run dev (assuming dependencies are installed)
3. npm run build check that it builds
4. npm run start preview

Publishing (access only)

Publish npm packages

1. Run lints, build packages, bump package versions and publish

   npm run release

Detecting circular dependencies

If you suspect you have caused a circular dependency (easily done in monorepos), you can run npx madge -c in the project root.

Deploying documentation

Merge into branch preview (for preview) or branch docs for live. The CI/CD workflows will automatically build the Nextra documentation site and deploy it to Cloudflare.

Credits

TSDL was originally created by the developers at Enter Technologies, it's used internally on projects such as GyRank and markanvisning.se but was later open sourced.

• Nextra for documentation
• TanStack Query for the awesome query library
• gRPC/tRPC for inspiration (see migration guide from gRPC/tRPC to TSDL)
• Nx cloud runs
• Lerna monorepo tool
• TypeScript
• Vitest unit testing

This README is auto-generated