# @yme/api

> Simply create some request functions

Latest version **2.2.1** (published 2025-03-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @yme/api
pnpm add @yme/api
yarn add @yme/api
bun add @yme/api
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.1 |
| Published | 2025-03-09 |
| First published | 2023-04-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 45 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | mino |
| Maintainers | minosss |
| Keywords | api, client, rest, http, https, nextjs |

## Links

- npm: https://www.npmjs.com/package/@yme/api
- Repository: https://github.com/minosss/api
- Homepage: https://github.com/minosss/api#readme
- Issues: https://github.com/minosss/api/issues
- npm.io page: https://npm.io/package/@yme/api

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.2.1 (latest) — 2025-03-09
- 2.0.0-alpha.13 (next) — 2024-11-15
- 2.2.0 — 2025-02-17
- 2.1.2 — 2025-02-12
- 2.1.1 — 2024-12-02
- 2.1.0 — 2024-11-24
- 2.0.1 — 2024-11-18
- 1.4.2 — 2024-11-18
- 2.0.0-alpha.12 — 2024-11-09
- 2.0.0-alpha.11 — 2024-11-06
- 2.0.0-alpha.10 — 2024-11-04
- 2.0.0-alpha.9 — 2024-10-23
- 2.0.0-alpha.8 — 2024-10-22
- 2.0.0-alpha.7 — 2024-10-21
- 2.0.0-alpha.6 — 2024-10-21
- … 39 more at https://npm.io/package/@yme/api/versions

## README

Hey 👋, `@yme/api` is a package that defines the type-safe API requests. No server required and zero dependencies.

> If you are developing a full-stack web application, you should take a look [tRPC](https://trpc.io/).

[![NPM version](https://img.shields.io/npm/v/@yme/api)](https://www.npmjs.com/package/@yme/api)
[![NPM Downloads](https://img.shields.io/npm/dm/@yme/api)](https://www.npmjs.com/package/@yme/api)

- **Type-Safe**: Define API requests with TypeScript.
- **Zero Dependencies**: No dependencies.
- **Serverless**: No server required.
- **Customizable**: Use your own HTTP client.
- **Middlewares**: Support middlewares.

```
[input] -> [middlewares, action] -> [output]
```

## Migration from v1 to v2

Check out the [migration guide](./docs/migrations/v1-to-v2.md).

## Installation

```bash
npm install @yme/api
```

## Quick Start

Use `ApiClient` with `fetch` (Action first)

```ts
import { createClient, replacePathParams } from "@yme/api/client";
import { logger } from "@yme/api/middleware";

const api = createClient({
  action: async ({ req }) => {
    // make http request and return data
    const response = await fetch(req.url, {
      method: req.method,
      headers: req.headers,
      body: JSON.stringify(req.input),
    });
    // check status or others
    return response.json();
  },
  middlewares: [
    logger(),
    // replace path params from input. e.g. /users/[id] to /users/1
    replacePathParams(),
  ],
});

const createUser = api
  .post("/users", {
    // initial request config, like headers
  })
  .validator(
    // input schema
    z.object({
      name: z.string(),
      age: z.number(),
    })
  )
  .T<{ id: string; name: string }>()
  // output schema
  .selector((user) => user.id);

const newUserId = await createUser(
  {
    name: "Alice",
    age: 18,
  },
  {
    // request config
  }
);
```

Use `NextAction` for Next.js server action (Action last)

```ts
import { createAction } from "@yme/api/next";
const api = createAction({
  middlewares: [],
  // throwing an error will make the server return status 500
  // we can handle it in the error handler. e.g. returns a fallback data with error message
  handleError: async (err, opts) => {
    return {
      message: err.message,
      code: err.code,
    };
  },
});

const updateUser = api
  .post({
    // ...initial,
    actionName: "updateUser",
  })
  .validator(
    z.object({
      name: z.string(),
    })
  )
  .bindArgs([z.string()])
  .action(async ({ req }) => {
    const {
      parsedBindArgs: [id],
      parsedInput: { name },
      actionName, // "updateUser"
    } = req;
    return true;
  }); // updateUser(id: string, input: { name: string } | FormData): Promise<boolean>

// use state
const createUser = api
  .post()
  .validator(
    z.object({
      name: z.string(),
    })
  )
  .state<{ message: string }>()
  .action(async ({ req }) => {
    // { state, parsedInput: { name } }
    return { message: "ok" };
  }); // createUser(state: { message: string }, input: { name: string } | FormData): Promise<{ message: string }>

const [state, action, isPending] = useFormState(createUser, {
  message: "",
});
```

## License

MIT

---
_Source: https://npm.io/package/@yme/api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._