Untypeable

Get type-safe access to any API, with a zero-bundle size option.

Data fetching
total-typescript/untypeableuntypeable

README

Untypeable


Get type-safe access to any API, with a zero-bundle size option.

The Problem


If you're lucky enough to use tRPC , GraphQL , or OpenAPI , you'll be able to get type-safe access to your API- either through a type-safe RPC or codegen.

But what about the rest of us?

What do you do if your API has no types?

Solution


Enter untypeable- a first-class library for typing API's you don't control.

🚀 Get autocomplete on your entire API*, without needing to set up a single generic function.
💪 Simple to configure, and extremely flexible*.
🤯* Choose between two modes:
Zero bundle-size: use import typeto ensure untypeableadds nothing to your bundle.
Strong types: integrates with libraries like Zod to add runtime safety to the types.

✨ Keep things organized*with helpers for merging and combining your config.
❤️ You bring the fetcher, we bring the types. There's no hidden magic*.

Quickstart


npm i untypeable

  1. ``` ts
  2. import { initUntypeable, createTypeLevelClient } from "untypeable";

  4. // Initialize untypeable
  5. const u = initUntypeable();

  7. type User = {
  8.   id: string;
  9.   name: string;
  10. };

  12. // Create a router
  13. // - Add typed inputs and outputs
  14. const router = u.router({
  15.   "/user": u.input<{ id: string }>().output<User>(),
  16. });

  18. const BASE_PATH = "http://localhost:3000";

  20. // Create your client
  21. // - Pass any fetch implementation here
  22. const client = createTypeLevelClient<typeof router>((path, input) => {
  23.   return fetch(BASE_PATH + path + `?${new URLSearchParams(input)}`).then(
  24.     (res) => res.json(),
  25.   );
  26. });

  28. // Type-safe data access!
  29. // - user is typed as User
  30. // - { id: string } must be passed as the input
  31. const user = await client("/user", {
  32.   id: "1",
  33. });
  34. ```

SWAPI Example


We've added a full example of typing swapi.dev.

Zero-bundle mode


You can set up untypeableto run in zero-bundle mode. This is great for situations where you trust the API you're calling, but it just doesn't have types.

To set up zero-bundle mode, you'll need to:

Define your router in a file called router.ts.
Export the type of your router: export type MyRouter = typeof router;

  1. ``` ts
  2. // router.ts

  4. import { initUntypeable } from "untypeable";

  6. const u = initUntypeable();

  8. type User = {
  9.   id: string;
  10.   name: string;
  11. };

  13. const router = u.router({
  14.   "/user": u.input<{ id: string }>().output<User>(),
  15. });

  17. export type MyRouter = typeof router;
  18. ```

In a file called client.ts, import createTypeLevelClientfrom untypeable/type-level-client.

  1. ``` ts
  2. // client.ts

  4. import { createTypeLevelClient } from "untypeable/client";
  5. import type { MyRouter } from "./router";

  7. export const client = createTypeLevelClient<MyRouter>(() => {
  8.   // your implementation...
  9. });
  10. ```

How does this work?


This works because createTypeLevelClientis just an identity function, which directly returns the function you pass it. Most modern bundlers are smart enough to collapse identity functions and erase type imports, so you end up with:

  1. ``` ts
  2. // client.ts

  4. export const client = () => {
  5.   // your implementation...
  6. };
  7. ```

Runtime-safe mode


Sometimes, you just don't trust the API you're calling. In those situations, you'll often like to validatethe data you get back.

untypeableoffers first-class integration with Zod . You can pass a Zod schema to u.inputand u.outputto ensure that these values are validated with Zod.

  1. ``` ts
  2. import { initUntypeable, createSafeClient } from "untypeable";
  3. import { z } from "zod";

  5. const u = initUntypeable();

  7. const router = u.router({
  8.   "/user": u
  9.     .input(
  10.       z.object({
  11.         id: z.string(),
  12.       }),
  13.     )
  14.     .output(
  15.       z.object({
  16.         id: z.string(),
  17.         name: z.string(),
  18.       }),
  19.     ),
  20. });

  22. export const client = createSafeClient(router, () => {
  23.   // Implementation...
  24. });
  25. ```

Now, every call made to client will have its inputand outputverified by the zod schemas passed.

Configuration & Arguments


untypeablelets you be extremely flexible with the shape of your router.

Each level of the router corresponds to an argument that'll be passed to your client.

  1. ``` ts
  2. // A router that looks like this:
  3. const router = u.router({
  4.   github: {
  5.     "/repos": {
  6.       GET: u.output<string[]>(),
  7.       POST: u.output<string[]>(),
  8.     },
  9.   },
  10. });

  12. const client = createTypeLevelClient<typeof router>(() => {});

  14. // Will need to be called like this:
  15. client("github", "/repos", "POST");
  16. ```

You can set up this argument structure using the methods below:

.pushArg


Using the .pushArgmethod when we initUntypeablelets us add new arguments that must be passed to our client.

  1. ``` ts
  2. import { initUntypeable, createTypeLevelClient } from "untypeable";

  4. // use .pushArg to add a new argument to
  5. // the router definition
  6. const u = initUntypeable().pushArg<"GET" | "POST" | "PUT" | "DELETE">();

  8. type User = {
  9.   id: string;
  10.   name: string;
  11. };

  13. // You can now optionally specify the
  14. // method on each route's definition
  15. const router = u.router({
  16.   "/user": {
  17.     GET: u.input<{ id: string }>().output<User>(),
  18.     POST: u.input<{ name: string }>().output<User>(),
  19.     DELETE: u.input<{ id: string }>().output<void>(),
  20.   },
  21. });

  23. // The client now takes a new argument - method, which
  24. // is typed as 'GET' | 'POST' | 'PUT' | 'DELETE'
  25. const client = createTypeLevelClient<typeof router>((path, method, input) => {
  26.   let resolvedPath = path;
  27.   let resolvedInit: RequestInit = {};

  29.   switch (method) {
  30.     case "GET":
  31.       resolvedPath += `?${new URLSearchParams(input as any)}`;
  32.       break;
  33.     case "DELETE":
  34.     case "POST":
  35.     case "PUT":
  36.       resolvedInit = {
  37.         method,
  38.         body: JSON.stringify(input),
  39.       };
  40.   }

  42.   return fetch(resolvedPath, resolvedInit).then((res) => res.json());
  43. });

  45. // This now needs to be passed to client, and
  46. // is still beautifully type-safe!
  47. const result = await client("/user", "POST", {
  48.   name: "Matt",
  49. });
  50. ```

You can call this as many times as you want!

  1. ``` ts
  2. const u = initUntypeable()
  3.   .pushArg<"GET" | "POST" | "PUT" | "DELETE">()
  4.   .pushArg<"foo" | "bar">();

  6. const router = u.router({
  7.   "/": {
  8.     GET: {
  9.       foo: u.output<string>,
  10.     },
  11.   },
  12. });
  13. ```

.unshiftArg


You can also add an argument at the startusing .unshiftArg. This is useful for when you want to add different base endpoints:

  1. ``` ts
  2. const u = initUntypeable().unshiftArg<"github", "youtube">();

  4. const router = u.router({
  5.   github: {
  6.     "/repos": u.output<{ repos: { id: string }[] }>(),
  7.   },
  8. });
  9. ```

.args


Useful for when you want to set the args up manually:

  1. ``` ts
  2. const u = initUntypeable().args<string, string, string>();

  4. const router = u.router({
  5.   "any-string": {
  6.     "any-other-string": {
  7.       "yet-another-string": u.output<string>(),
  8.     },
  9.   },
  10. });
  11. ```

Organizing your routers


.add


You can add more detail to a router, or split it over multiple calls, by using router.add.

  1. ``` ts
  2. const router = u
  3.   .router({
  4.     "/": u.output<string>(),
  5.   })
  6.   .add({
  7.     "/user": u.output<User>(),
  8.   });
  9. ```

.merge


You can merge two routers together using router.merge. This is useful for when you want to combine multiple routers (perhaps in different modules) together.

  1. ``` ts
  2. import { userRouter } from "./userRouter";
  3. import { postRouter } from "./postRouter";

  5. export const baseRouter = userRouter.merge(postRouter);
  6. ```