@alistt69/create-api One helper. No extra. A lightweight createApi inspired by RTKQ — with query, lazy query and mutation hooks & endpoint controllers, built-in cache utilities, stale data handling and a tiny, focused API.

---

Install · Quick Start · The Shape · Cache · Imperative API · Controller

---

Why this exists

@alistt69/create-api is for React projects that like the ergonomics of RTK Query, but do not want to introduce Redux just to fetch data.

It gives you a compact createApi workflow:

define endpoints -> get typed hooks -> read/write cache -> refetch when stale

Use it when you want:

You need	You get
Generated React hooks	useGetPostQuery, useLazyGetPostQuery, useUpdatePostMutation
A small HTTP layer	fetchBaseQuery, built on native fetch
Cache reads and patches	getQueryData, setQueryData, updateQueryData
Stale data handling	staleTime, keepUnusedDataFor, refetchOnMount
Manual orchestration	api.endpoints.*.initiate, select, subscribe
Store-based usage	createController from the controller subpath

Install

npm i @alistt69/create-api

Requirements:

Runtime	Version
Node.js	>=18
React	>=16.8

Quick Start

Create an API once:

import { createApi, fetchBaseQuery } from '@alistt69/create-api';

const api = createApi({
  baseQuery: fetchBaseQuery({
    baseUrl: 'https://example.com/api',
  }),

  endpoints: (builder) => ({
    getPost: builder.query({
      query: (id: string) => ({
        url: `/posts/${id}`,
      }),
    }),

    updatePost: builder.mutation({
      query: ({ id, title }: { id: string; title: string }) => ({
        url: `/posts/${id}`,
        method: 'PATCH',
        body: { title },
      }),
    }),
  }),
});

Then use the generated hooks:

function Post() {
  const { data, isLoading, refetch } = api.useGetPostQuery('1');
  const [updatePost, updateState] = api.useUpdatePostMutation();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <section>
      <h2>{data?.title}</h2>

      <button
        disabled={updateState.isLoading}
        onClick={() => updatePost({ id: '1', title: 'Updated' })}
      >
        Update
      </button>

      <button onClick={() => refetch()}>
        Refetch
      </button>
    </section>
  );
}

The Shape

The package is intentionally small, but the surface area covers the core data-fetching loop.

Query hooks

const result = api.useGetPostQuery('1', {
  enabled: true,
  refetchOnMount: true,
});

Query state includes:

Field	Meaning
data	Last successful value
error	Last failed value
status	uninitialized, pending, fulfilled or rejected
isLoading	First request is in progress
isFetching	Any request is in progress, including background refetch
isSuccess	Last known state is successful
isError	Last known state is failed
fulfilledAt	Timestamp of the last fulfilled request
requestId	Active or last request id

Lazy query hooks

const [loadPost, post] = api.useLazyGetPostQuery();

await loadPost('1');

post.refetch();

Lazy queries are useful when the request should start from a user action, a modal opening, a route transition or another explicit event.

Mutation hooks

const [updatePost, updateState] = api.useUpdatePostMutation();

await updatePost({ id: '1', title: 'Updated' });

updateState.reset();

Mutation state tracks the latest trigger. This keeps UI behavior predictable when several mutation calls overlap.

fetchBaseQuery

fetchBaseQuery is a ready-to-use baseQuery built on top of native fetch. It handles URLs, params, JSON bodies, headers, timeouts and response parsing.

import { createApi, fetchBaseQuery } from '@alistt69/create-api';

const api = createApi({
  baseQuery: fetchBaseQuery({
    baseUrl: 'https://example.com/api',
    timeout: 10_000,
    credentials: 'include',
    prepareHeaders: (headers) => {
      headers.set('authorization', 'Bearer token');
      return headers;
    },
  }),

  endpoints: (builder) => ({
    getTickets: builder.query({
      query: ({ page }: { page: number }) => ({
        url: '/tickets',
        params: { page },
      }),
    }),
  }),
});

Supported options:

Option	Where	Purpose
baseUrl	base query	Prefix all request URLs
headers	request	Add request-specific headers
prepareHeaders	base query	Modify headers before every request
params	request	Append query params
paramsSerializer	base query	Customize query string serialization
body	request	Send JSON, FormData, Blob, URLSearchParams or another fetch body
credentials	both	Control cookie/auth credential handling (omit, same-origin, include)
timeout	both	Abort slow requests
responseHandler	both	Parse as json, text, content-type or custom handler
validateStatus	both	Decide whether a response is success
fetchFn	base query	Use a custom fetch implementation

Custom response handling:

downloadReport: builder.query({
  query: () => ({
    url: '/report',
    responseHandler: (response) => response.blob(),
  }),
});

Cache

Queries are cached by endpoint name and serialized argument.

const api = createApi({
  baseQuery,
  endpoints: (builder) => ({
    getTicketById: builder.query({
      query: (id: string) => ({ url: `/tickets/${id}` }),
      serializeArgs: (id) => id,
      staleTime: 2_000,
      keepUnusedDataFor: 10_000,
    }),
  }),
});

Cache controls:

Option	Behavior
serializeArgs	Builds the cache key for an endpoint argument
staleTime	Keeps fulfilled data fresh for automatic mount behavior
keepUnusedDataFor	Keeps unused cache alive after the last subscriber leaves
refetchOnMount	Controls whether cached data may refetch on mount
enabled	Disables automatic query execution while keeping manual refetch available

Manual cache updates:

api.util.getQueryData('getPost', '1');

api.util.setQueryData('getPost', '1', {
  id: '1',
  title: 'Local title',
});

api.util.updateQueryData('getPost', '1', (prev) => ({
  ...prev,
  title: 'Patched title',
}));

Invalidation

Use endpoint-level invalidation for broad refetching:

editTicket: builder.mutation({
  query: ({ id, title }) => ({
    url: `/tickets/${id}`,
    method: 'PATCH',
    body: { title },
  }),
  invalidates: ['getTickets'],
});

Use tag invalidation when you want to target specific cached records:

getTicketById: builder.query({
  query: (id) => ({ url: `/tickets/${id}` }),
  providesTags: (_result, id) => [`Ticket/${id}`],
}),

editTicket: builder.mutation({
  query: ({ id, title }) => ({
    url: `/tickets/${id}`,
    method: 'PATCH',
    body: { title },
  }),
  invalidatesTags: (_result, arg) => [`Ticket/${arg.id}`],
});

Imperative API

Every endpoint also exposes a small imperative API. It is useful when a query lifecycle should live outside React components.

const request = api.endpoints.getPost.initiate('1');

const data = await request.unwrap();

await request.refetch();

request.unsubscribe();
request.abort();

You can also inspect query state directly:

const state = api.endpoints.getPost.select('1');

And trigger mutations:

const mutation = api.endpoints.updatePost.initiate({
  id: '1',
  title: 'Updated',
});

await mutation.unwrap();

mutation.abort();

Controller

For store-based usage, import createController from the controller subpath:

import { createController } from '@alistt69/create-api/controller';

class TicketStore {
    private ticket = createController(api.endpoints.getTicketById);
    private editTicket = createController(api.endpoints.editTicket);

    ticketState = this.ticket.state;
    editTicketState = this.editTicket.state;

    private unsubscribers = [
        this.ticket.subscribe(() => {
            this.ticketState = this.ticket.state;
        }),
        this.editTicket.subscribe(() => {
            this.editTicketState = this.editTicket.state;
        }),
    ];

    load(id: string) {
        return this.ticket.run(id);
    }

    save(id: string, title: string) {
        return this.editTicket.run({ id, title });
    }

    get ticketData() {
        return this.ticketState.data;
    }

    get isLoadingTicket() {
        return this.ticketState.isLoading;
    }

    get isSavingTicket() {
        return this.editTicketState.isLoading;
    }

    destroy() {
        this.unsubscribers.forEach((unsubscribe) => unsubscribe());
        this.ticket.dispose();
        this.editTicket.dispose();
    }
}

The controller keeps endpoint state outside React, subscribes to cache updates, and releases its subscription with dispose().

Demo

Live demo

Sandbox is coming soon.

License

MIT. See LICENSE.