reactscrew

A typed React data layer built around domain modules called screws.

Features

Typed hooks — useScrewQuery, useScrewMutation with full generic inference
Cache — In-memory cache with deduplication, invalidation, and versioned persistence
Multi-backend — Route queries/mutations to different APIs by screw name
Infinite queries — Cursor/page-based pagination out of the box
Hydration — SSR/SSG via dehydrate / hydrate
Observability — Devtools panel, request event stream, Sentry/OpenTelemetry integrations
Orchestration — Batch, workflow, and progress tracking across backends
Transport adapters — fetch and axios, with auth retry and proxy rewriting
OpenAPI generation — Generate screws, hooks, types, and validators from OpenAPI specs
Error contract — Unified ReactScrewError with code, status, retryable, uiHint
UX feedback — Toast notifications and loading indicators wired to request lifecycle
Legacy API — useScrew for gradual migration

Installation

npm install reactscrew

react and react-dom (≥18) are peer dependencies.

Quick Start

import { createRoot } from 'react-dom/client';
import { DriverProvider, createFetchAdapter, useScrewQuery } from 'reactscrew';

const api = createFetchAdapter('https://jsonplaceholder.typicode.com');

const userScrew = {
  name: 'user',
  methods: {
    list: { type: 'query', route: '/users', httpMethod: 'GET' },
    create: {
      type: 'mutation',
      route: '/users',
      httpMethod: 'POST',
      invalidateQueries: [{ screwName: 'user', methodName: 'list' }]
    }
  }
};

function App() {
  const { data, isLoading } = useScrewQuery('user', 'list');
  if (isLoading) return <p>Loading...</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

createRoot(document.getElementById('root')).render(
  <DriverProvider apiInstance={api} screws={{ user: userScrew }}>
    <App />
  </DriverProvider>
);

1. Declaring a Screw

A screw is a domain module that declares its API endpoints, validators, cache configuration, and invalidation relationships.

Basic Structure

import type { ScrewDefinition } from 'reactscrew';

const productScrew: ScrewDefinition = {
  name: 'product',
  methods: {
    // ── Query (GET) ──
    list: {
      type: 'query',
      route: '/products',
      httpMethod: 'GET',
      staleTime: 30_000,          // 30s before stale
      cacheTime: 5 * 60_000,     // 5min before garbage collection
      refetchOnWindowFocus: true,
    },

    // ── Query with parameters ──
    get: {
      type: 'query',
      route: (params: { id: number }) => `/products/${params.id}`,
      httpMethod: 'GET',
      queryKey: ({ screwName, methodName, args }) =>
        [screwName, methodName, args[0] ?? null],
    },

    // ── Mutation (POST) with invalidation ──
    create: {
      type: 'mutation',
      route: '/products',
      httpMethod: 'POST',
      invalidateQueries: [
        { screwName: 'product', methodName: 'list' }
      ],
    },

    // ── Mutation (PATCH) with optimistic update ──
    update: {
      type: 'mutation',
      route: (params: { id: number }) => `/products/${params.id}`,
      httpMethod: 'PATCH',
      optimisticUpdate: async ({ client, variables }) => {
        await client.setQueryData(['product', 'get'], (prev) => ({
          ...prev, ...variables
        }));
        return { rollback: () => {} };
      },
    },
  },
};

Method Properties

Property	Type	Description
`type`	`'query' \| 'mutation'`	Inferred from `httpMethod` if omitted
`route`	`string \| (...args) => string`	URL template
`httpMethod`	`'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'`	HTTP verb
`staleTime`	`number` (ms)	Duration before data is considered stale
`cacheTime`	`number` (ms)	In-memory retention duration
`refetchOnWindowFocus`	`boolean`	Refetch on window focus
`refetchOnReconnect`	`boolean`	Refetch on network reconnection
`queryKey`	`(ctx) => QueryKey`	Custom cache key
`invalidateQueries`	`QueryInvalidationTarget[]`	Screws to invalidate after mutation
`optimisticUpdate`	`(ctx) => RollbackAction`	Optimistic update logic
`onSuccess` / `onError` / `onSettled`	`function`	Lifecycle callbacks
`headers`	`Record<string, string>`	Custom headers
`paramsValidator` / `responseValidator`	`RuntimeValidator`	Runtime validation
`documentedErrors`	`DocumentedErrorDefinition[]`	Error catalog

Screws are used with useScrewQuery / useScrewMutation:

const { data } = useScrewQuery('product', 'list');
const { mutate } = useScrewMutation('product', 'create');

2. Multi-Backend Management

reactscrew can route requests to multiple independent APIs from a single DriverProvider.

Configuration

import { DriverProvider, useScrewQuery, createFetchAdapter } from 'reactscrew';

const productsApi = createFetchAdapter('https://fakestoreapi.com');
const usersApi = createFetchAdapter('https://jsonplaceholder.typicode.com');

const backends = {
  products: {
    apiInstance: productsApi,
    screws: {
      product: {
        name: 'product',
        methods: {
          list: { type: 'query', route: '/products', httpMethod: 'GET' },
        },
      },
    },
  },
  users: {
    apiInstance: usersApi,
    screws: {
      user: {
        name: 'user',
        methods: {
          list: { type: 'query', route: '/users', httpMethod: 'GET' },
        },
      },
    },
  },
};

function App() {
  return (
    <DriverProvider backends={backends}>
      <ProductList />
      <UserList />
    </DriverProvider>
  );
}

Automatic Routing

useScrewQuery('product', 'list') searches for the product screw across all backends and routes to the correct client automatically.

// Automatic routing (by screw name)
const { data: products } = useScrewQuery('product', 'list');
const { data: users } = useScrewQuery('user', 'list');

// Explicit routing
const { data } = useScrewQuery('product', 'list', { backend: 'products' });

Isolation

Each backend has its own cache, its own metrics, and its own events. Data from one backend never leaks into another.

Mix legacy + backends

<DriverProvider
  apiInstance={defaultApi}
  screws={{ legacy: { name: 'legacy', methods: { ... } } }}
  backends={{
    billing: { apiInstance: billingApi, screws: { invoice: { ... } } },
  }}
/>

3. OpenAPI Generation

reactscrew can generate complete screws, TypeScript hooks, types, and validators from an OpenAPI 3.0/3.1 file.

Exposed API (browser-safe)

These functions are exported from the main barrel:

import {
  parseOpenApiDocument,          // Parse an OpenAPI document → contract
  validateOpenApiContract,       // Validate the parsed contract
  generateScrewsFromOpenApiContract,  // Generate screw definitions (string)
  generateOpenApiArtifacts,      // Generate all artifacts (types, hooks, validators, errors, screws)
  generateOpenApiArtifactsFromDocument, // Direct version (no file)
  loadOpenApiContract,           // (Node.js) Load a file or URL
} from 'reactscrew';

Generation from a file (Node.js)

npx reactscrew-openapi openapi.json ./output

Produces 9 files:

output/
├── index.ts
├── custom/index.ts          ← preserved on regeneration
├── wrappers/index.ts        ← preserved on regeneration
└── generated/
    ├── index.ts
    ├── types/index.ts       ← TypeScript interfaces
    ├── errors/index.ts      ← documented error catalog
    ├── validators/index.ts  ← runtime validators
    ├── screws/index.ts      ← screw definitions
    └── hooks/index.ts       ← typed hooks (useXQuery, useXMutation)

Example e-commerce spec

{
  "openapi": "3.0.0",
  "info": { "title": "Products API", "version": "1.0.0" },
  "paths": {
    "/products": {
      "get": {
        "operationId": "listProducts",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "price": { "type": "number" }
        }
      }
    }
  }
}

Generates:

// screws
const productsScrew = {
  name: "products",
  methods: {
    listProducts: {
      type: 'query',
      route: (params) => `/products?category=${params.category}`,
      httpMethod: 'GET',
      paramsValidator: validateListProductsParamsArgs,
      responseValidator: validateListProductsResponse,
    }
  }
};

// typed hook
const { data } = useListProductsQuery({ category: 'electronics' });

Available e-commerce specs

The examples/e-commerce/openapi/ directory contains 3 specs:

File	Generated Screws	Endpoints
`users.openapi.json`	`users`, `auth`, `wishlist`	6 (CRUD users, login, wishlist)
`products.openapi.json`	`products`, `categories`	5 (catalog, categories)
`orders.openapi.json`	`cart`, `orders`	7 (cart, checkout, orders)

Usage:

node scripts/generate-openapi-screws.mjs examples/e-commerce/openapi/products.openapi.json ./generated/products

4. Orchestration

reactscrew offers three orchestration levels: batch, workflow, and progress tracking.

Batch — Parallel action execution

executeBatch runs a list of mutation actions (potentially across multiple backends) and reports progress.

import { useScrewBatch } from 'reactscrew';

function CheckoutAll() {
  const { execute, progress, isExecuting } = useScrewBatch([
    { screwName: 'order', methodName: 'checkout', variables: { cartId: 1 }, backend: 'orders' },
    { screwName: 'inventory', methodName: 'reserve', variables: { productId: 5 }, backend: 'products' },
  ]);

  return (
    <button onClick={() => execute()} disabled={isExecuting}>
      {isExecuting ? `⏳ ${progress?.percentage}%` : '⚡ Order all'}
    </button>
  );
}

Workflow — Sequential orchestration with dependencies

executeWorkflow runs steps with dependencies, retry, parallel mode, and conditional gating.

import { executeWorkflow, useScrewWorkflow } from 'reactscrew';

function CheckoutWorkflow() {
  const { execute, progress } = useScrewWorkflow({
    steps: [
      { id: 'reserve',  screwName: 'inventory', methodName: 'reserve',  variables: { productId: 5 } },
      { id: 'payment',  screwName: 'billing',   methodName: 'charge',   variables: { amount: 99 }, dependsOn: ['reserve'] },
      { id: 'ship',     screwName: 'logistics', methodName: 'ship',     variables: { orderId: 1 },  dependsOn: ['payment'], retry: 2 },
      { id: 'notify',   screwName: 'notifications', methodName: 'email', variables: { userId: 1 },  dependsOn: ['ship'],   continueOnError: true },
    ],
  });

  return <button onClick={() => execute()}>🔁 Run workflow</button>;
}

Workflow-level conditions

A workflow can have a global condition evaluated before any step runs. When paired with waitForCondition: true, the workflow polls every 500ms and re-evaluates the condition until it passes (up to 30s).

const result = await executeWorkflow({
  steps: [
    { id: 'checkout', screwName: 'orders', methodName: 'checkout', variables: { shippingAddress } },
    { id: 'tracking', screwName: 'delivery', methodName: 'track', args: [{ orderId: 0 }], dependsOn: ['checkout'] },
  ],
  condition: (ctx) => {
    const cart = ctx.getScrewData('cart', 'get');
    return cart?.items?.length >= (ctx.variables?.minItems ?? 1);
  },
  waitForCondition: true,
  variables: { minItems: 1 },
  onStepCondition: (result) => {
    if (!result.passed) console.log(`⏳ Waiting for "${result.stepId}"`);
  },
}, { client, resolveClient, onProgress });

condition — receives { stepResults, getScrewData, variables }. Return true to proceed.
waitForCondition — if the condition returns false, the workflow re-polls.
variables — arbitrary data injected into the condition context via ctx.variables.
onStepCondition — callback when a step-level or workflow-level condition is evaluated.

Step-level conditions

Individual steps can also have conditions:

{
  id: 'apply-discount',
  screwName: 'cart',
  methodName: 'applyCoupon',
  condition: (ctx) => ctx.stepResults['checkout']?.data?.couponApplied === true,
  waitForCondition: true,
}

Declarative workflows in screw definitions

Workflows can be declared directly in a ScrewDefinition and auto-executed:

const cartScrew: ScrewDefinition = {
  name: 'cart',
  methods: { get: { type: 'query', route: '/cart', httpMethod: 'GET' } },
  workflows: {
    checkout: {
      config: {
        steps: [
          { id: 'validate', screwName: 'cart', methodName: 'get', label: 'Stock check' },
          { id: 'checkout', screwName: 'orders', methodName: 'checkout', dependsOn: ['validate'] },
        ],
        condition: (ctx) => {
          const cart = ctx.getScrewData('cart', 'get');
          return cart?.items?.length > 0;
        },
        waitForCondition: true,
        variables: { minItems: 1 },
      },
      autoStart: false,
    },
  },
};

Use useScrewAutoWorkflow to execute a declared workflow by passing its config:

const { start, progress, status } = useScrewAutoWorkflow({
  config: { steps, condition, waitForCondition, variables },
  onProgress: (snap) => setProgress(snap),
});

Progress Tracking

useScrewProgress derives a unified ProgressSnapshot from any batch or workflow source:

import { useScrewBatch, useScrewProgress } from 'reactscrew';

function ProgressBar() {
  const batch = useScrewBatch([...]);
  const progress = useScrewProgress(batch);

  if (!progress || progress.phase === 'idle') return null;

  return (
    <div>
      <progress value={progress.percentage} max={100} />
      <span>{progress.percentage}% · {progress.itemsProcessed}/{progress.itemsTotal}</span>
    </div>
  );
}

SSR / Server Components

All hooks and DriverProvider are marked 'use client'. They are safe for use in Next.js App Router client boundaries.

SSR data prefetching uses createReactScrewClient (exported from the package):

// app/page.tsx — Server Component
import { createFetchAdapter, createReactScrewClient } from 'reactscrew';
import { userScrew } from '../screws/user';

export default async function Page() {
  const client = createReactScrewClient(api, { user: userScrew });
  await client.prefetchQuery('user', 'list');
  const dehydratedState = client.dehydrate();

  return <UsersClient dehydratedState={dehydratedState} />;
}

// app/users-client.tsx — Client Component
'use client';
import { DriverProvider, useScrewQuery } from 'reactscrew';

export default function UsersClient({ dehydratedState }) {
  return (
    <DriverProvider apiInstance={api} screws={{ user: userScrew }}
      dehydratedState={dehydratedState}>
      <UsersList />
    </DriverProvider>
  );
}

Limits:

Hooks are client-only ('use client' boundary). No RSC-specific exports.
Cache persistence (persist option) uses localforage (IndexedDB). Do not enable in SSR; it will be safely ignored.
createReactScrewClient is pure and safe for server usage; use for prefetch in Server Components or Route Handlers.

Documentation

Topic	Resource
Execution roadmap	TASK.md
Vision & levels	evolving.md
Full API reference	API_REFERENCE.md — every hook, component, function, and type
Best practices	BEST_PRACTICES.md — cache strategy, configuration values, pitfalls
TypeScript types	src/index.ts (JSDoc per export)
Multi-backend e-commerce demo	examples/e-commerce
OpenAPI 3.0 specs	examples/e-commerce/openapi/
Generated artifacts	examples/e-commerce/generated/
Examples	examples/basic, examples/openapi-generated, examples/next-app-router

Performance

Benchmarks measured on Node.js v22.22.0, Linux, against a local loopback HTTP server (~2ms network latency per request). All figures are the average of 30–500 iterations.

Benchmark	avg	p50	p95
Cold query (first fetch, ~2ms network)	5.24 ms	3.63 ms	8.58 ms
Warm query (from cache)	3.28 ms	3.25 ms	3.81 ms
Cold slow query (~30ms network)	31.22 ms	31.24 ms	31.72 ms
Mutation execution	3.69 ms	3.55 ms	4.32 ms
Concurrent dedup (5 identical requests, 1 network call)	3.35 ms	—	—
Batch (5 items, parallel)	0.42 ms	—	—
Workflow (3 sequential steps)	0.21 ms	—	—
OpenAPI parse (15-endpoint document)	0.18 ms	0.14 ms	0.23 ms
Logger.info (enabled, JSON output)	0.037 ms	0.022 ms	0.030 ms
Logger.debug (filtered by log level, ~0 cost)	0.001 ms	—	—

Bundle size: dist/=616 KB (38 files), gzipped=62.7 KB. Barrel re-export: 6.9 KB. Tree-shaking eliminates unused modules.

Cache overhead: ~0.5 KB per cache entry (based on 500 entries). Concurrent dedup routes identical requests through a single network call — subsequent subscribers await the same in-flight promise.

Scripts

npm run typecheck   # TypeScript strict check
npm run test        # Vitest (136 tests)
npm run lint        # ESLint
npm run build       # tsc → dist/
npm run demo        # Webpack dev server (e-commerce demo)
DEMO=basic npm run demo  # Basic demo alternative

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
scripts		scripts
src		src
test		test
.babelrc		.babelrc
.gitignore		.gitignore
.npmignore		.npmignore
API_REFERENCE.md		API_REFERENCE.md
BEST_PRACTICES.md		BEST_PRACTICES.md
MVP.md		MVP.md
README.md		README.md
TASK.md		TASK.md
TODO.md		TODO.md
eslint.config.mjs		eslint.config.mjs
evolving.md		evolving.md
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
webpack.config.js		webpack.config.js

Navigation Menu

Repository files navigation

reactscrew

Features

Installation

Quick Start

1. Declaring a Screw

Basic Structure

Method Properties

2. Multi-Backend Management

Configuration

Automatic Routing

Isolation

Mix legacy + backends

3. OpenAPI Generation

Exposed API (browser-safe)

Generation from a file (Node.js)

Example e-commerce spec

Available e-commerce specs

4. Orchestration

Batch — Parallel action execution

Workflow — Sequential orchestration with dependencies

Workflow-level conditions

Step-level conditions

Declarative workflows in screw definitions

Progress Tracking

SSR / Server Components

Documentation

Performance

Scripts

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

reactscrew

Features

Installation

Quick Start

1. Declaring a Screw

Basic Structure

Method Properties

2. Multi-Backend Management

Configuration

Automatic Routing

Isolation

Mix legacy + backends

3. OpenAPI Generation

Exposed API (browser-safe)

Generation from a file (Node.js)

Example e-commerce spec

Available e-commerce specs

4. Orchestration

Batch — Parallel action execution

Workflow — Sequential orchestration with dependencies

Workflow-level conditions

Step-level conditions

Declarative workflows in screw definitions

Progress Tracking

SSR / Server Components

Documentation

Performance

Scripts

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages