A Deep Dive into endpoint-plus: A Next-Gen, AI-Native Request Suite

💡

GitHub Repository:[github.com/zandko/endpoint-plus]

🌟 If you find this project helpful or inspiring, please give us aStar! We are actively looking for feedback, issues, and PRs to co-create the future of this project.

In modern frontend engineering, network requests are much more complex than simply fetching some JSON data. Around every API call, developers must wrestle with four persistent daily headaches:

interfaces

by hand, or constantly paste them into unstable online formatters. Whenever an API field changes, updating types turns into a maintenance nightmare.fetch

or axios

. But WeChat Mini-programs and uni-app require proprietary wrapper APIs (wx.request

or uni.request

). Meanwhile, SSR contexts (like Nuxt/Next) require server-compatible clients. You end up maintaining three separate copies of headers, interceptors, and error handlers.To solve these exact challenges, we built and open-sourced ** endpoint-plus** — a

endpoint-plus

avoids the monolithic overhead of traditional request clients by introducing a highly abstract physical Transport Layer alongside a pluggable middleware pipeline.

graph TD
    A[API Calls in Application Code] --> B[endpoint-plus Core Client]
    B --> C[Interceptors & Onion-Model Middleware]
    C --> D[Transport Layer Interface]

    D -- Web / Node SSR --> E[Fetch / Axios Transport]
    D -- Miniapp / uni-app --> F[Miniapp Transport]

    B <--> G[Vite DevTools Plugin]
    G -- TS Compiler AST Scan --> H[Scan Source Code]
    G -- Capture Real Response --> I[Schema Inference quicktype]
    I --> J[Write local endpoint-types.d.ts]

By splitting request definition from the actual underlying network implementation, endpoint-plus

provides 100% unified code semantics. You simply swap the transport adapter upon client creation:

  import { createInstance, createFetchTransport } from 'endpoint-plus';
  const api = createInstance({ transport: createFetchTransport() });
js
  import { createMiniappTransport } from 'endpoint-plus/miniapp';
  const api = createInstance({ transport: createMiniappTransport({ runtime: wx }) });
js
  import { createAxiosTransport } from 'endpoint-plus/transports/axios';
  const api = createInstance({ transport: createAxiosTransport() });

In addition to traditional request/response interceptors, endpoint-plus

introduces a Koa/Express-style Onion-Model Middleware system. This lets you wrap the entire execution lifespan using async functions:

api.registerRequestMiddleware(async (config, next) => {
  const start = Date.now();
  try {
    // 1. Outer Onion layer: Executed before request dispatch
    const response = await next(config);
    // 2. Inner Onion layer: Executed after response resolves
    console.log(`Request to ${config.url} took ${Date.now() - start}ms`);
    return response;
  } catch (error) {
    // 3. Centralized error catching and circuit-breaking
    console.error('Middleware caught exception:', error);
    throw error;
  }
});

This is the killer type-safety feature of endpoint-plus

: You do not need to manually cast generic arguments on every request. TypeScript parses the URL string and infers the correct response type directly at compile-time.

For instance, once you declare your routes in a .d.ts

file:

declare module 'endpoint-plus' {
  namespace YwEndpoint {
    interface Routes {
      'GET /users': { response: User[] };
      'GET /users/:userId': { response: User };
      'POST /users': { response: User };
    }
  }
}

Your editor instantly provides type-safety and autocompletion:

// 🌟 TypeScript 5.0+ const generic parameter pattern matching
const userList = await api.get('/users');
//    ^? User[] (Inferred from GET /users)

const user = await api.get('/users/123');
//    ^? User (Even with a concrete ID '123', the parser matches it against ':userId' to return User)

// ❌ Typos and invalid paths are caught instantly by the compiler!
const err = await api.get('/usrs'); // TS Compiler Error

We leverage recursive conditional types to strip URL queries, hash anchors, and domain prefixes, parsing the path into segments and pattern-matching them against parameter templates:

type EndpointRoutePathMatches<
  TRoutePath extends string,
  TUrl extends string,
> = EndpointPathSegmentsMatch<
  EndpointSplitPath<TRoutePath>,
  EndpointSplitPath<EndpointUrlPath<TUrl>>
>;

This ensures strict backend-to-frontend type alignment without requiring heavy code-generation steps during hot-reloads.

Writing interface types by hand is tedious. That's why we built ** endpoint-plus-devtools** (a Vite plugin).

Just add it to your vite.config.ts

:

import { endpointPlusDevtools } from 'endpoint-plus-devtools/vite';

export default defineConfig({
  plugins: [endpointPlusDevtools()],
});

.ts

, .tsx

, .vue

) in the background, identifying all api.get

/ api.post

calls to build a visual endpoint map.quicktype-core

engine runs schema analysis to write clean, type-safe ambient declarations into your project.src/

ordinarily triggers Vite's hot-reload, which reloads the page and destroys the active DevTools state. We resolved this by explicitly invoking Vite's watcher API (server.watcher.unwatch(typegenAbsFile)

) to temporarily exclude the generated .d.ts

file from HMR loops, ensuring silent, instantaneous type updates.launch-editor

Node utility, With the explosion of LLMs (like ChatGPT and Claude), Server-Sent Events are standard for token streaming. However, rendering updates on every single token (which can fire 30–50 times per second) results in high CPU usage and severe UI lag.

endpoint-plus

provides a native SSE extension with an integrated ** eventBuffer batching queue**:

import { createSseExtension } from 'endpoint-plus/extensions/sse';

const apiWithSse = api.use(createSseExtension());

await apiWithSse.sse<string>('/api/chat/stream', {
  method: 'POST',
  data: { prompt: 'Explain Quantum Computing' },

  // 🌟 High-performance animation frame rendering batcher
  eventBuffer: {
    maxDelay: 16,               // Flush every 16ms (matches 60Hz display frame rate)
    maxSize: 50,                // Max queue size
    strategy: 'animation-frame', // Batching strategy
  },

  // Token events are automatically accumulated and flushed, keeping UI frame rates stable!
  onBatch: (events) => {
    const chunkText = events.map(e => e.data).join('');
    appendChatText(chunkText);
  },
});

Furthermore, SSE streams automatically reuse global client headers, interceptors, authentication context (auth-token

), and telemetry configurations.

We believe in keeping bundles small. Everything in endpoint-plus

is modular, allowing you to opt-in to plugins on-demand:

import { createRefreshTokenPlugin } from 'endpoint-plus/plugins/refresh-token';

api.use(
  createRefreshTokenPlugin({
    refreshRequest: {
      method: 'POST',
      url: '/auth/refresh-token',
    },
    resolveAccessToken: (res) => res.newAccessToken,
    onRefresh: async (session) => {
      // Safely saves the new token. 
      // All other parallel requests are queued and automatically replayed.
      await saveSession(session);
    },
  })
);

To make AI assistants write accurate code, endpoint-plus

includes preloaded AI Skills inside the package folder.

Copy them to your local customizations directory:

mkdir -p .agents/skills
cp -r node_modules/endpoint-plus/skills .agents/skills/endpoint-plus

Once copied, your AI assistant (e.g. Cursor or Antigravity) will instantly read these files and learn our API layouts, SSE buffering options, and middleware patterns. You can prompt Cursor:

"Write an endpoint configuration with silent token refresh, deduplication gating, and export a get method"

The AI will output 100% accurate, compile-safe configurations without any hallucinated methods or parameters!

endpoint-plus

is published under the permissive MIT License and is already powering complex, high-traffic cross-platform apps in production.

We welcome community feedback, pull requests, and ideas! We are actively seeking contributors for:

If you like the project, check out our repository and drop us a Star ⭐️!

pnpm add endpoint-plus