apixa 0.0.0-stage → 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdalrahman bani younes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,302 @@
-# Temporary Holding Version
+# Apixa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Define your API once. Use it everywhere.**
+
+Apixa is an open-source, TypeScript-first library for defining APIs and generating fully typed API clients from a single source of truth.
+
+Instead of repeatedly writing request functions, types, URL construction, and response handling for every resource, Apixa aims to let you define your API once and handle the repetitive mechanics automatically.
+
+## Why Apixa?
+
+Working with APIs often means repeating the same patterns across resources and projects:
+
+- Writing request functions for every endpoint.
+- Maintaining request and response types separately.
+- Reimplementing headers, parsing, and error handling.
+- Repeating common resource operations.
+- Integrating API calls with different data-fetching libraries.
+
+Apixa aims to reduce this duplication while preserving TypeScript's type safety and flexibility.
+
+## Installation
+
+Apixa publishes one npm package: `apixa` (`1.0.0-rc.0`, ESM, Node.js 22+). The RC is prepared
+locally and has not been published. After release, install it with:
+
+```sh
+npm install apixa
+# React applications also install the optional peers:
+npm install apixa react @tanstack/react-query
+```
+
+```ts
+import { defineApi, defineApis, defineMockApi } from "apixa";
+import { MockStore } from "apixa/core";
+import "apixa/mocking/register";
+import { users } from "apixa/mocking/datasets/users";
+import { listDatasets } from "apixa/mocking/node"; // Node-only
+```
+
+```tsx
+import {
+  QueryClient,
+  ApixaProvider,
+  ApixaHydrationBoundary,
+  useResource,
+  useResourceQuery,
+  useResourceMutation,
+} from "apixa/react";
+// Server Components use the server-safe entry:
+import { QueryClient as ServerQueryClient, dehydrate } from "apixa/react/advanced";
+```
+
+Framework subpaths keep integrations isolated. Root, Core and Mocking imports require neither
+React nor TanStack Query. React and TanStack Query are optional peers, left external to the
+library build; install them only when using `apixa/react`. Missing peers produce the loader's
+module-not-found error when a React entry is imported. Future `apixa/vue` and `apixa/angular`
+subpaths are planned, not implemented.
+
+Core, Mocking, React and shared integration helpers remain private workspace modules. Their
+canonical code is compiled into one distribution with shared runtime chunks. No scoped package
+installation is required. See the [installation guide](./docs/guides/humans/install-apixa.md)
+and [public API contract](./docs/public-api.md).
+
+### Runtime support
+
+| Runtime                                      | Status                                                                                                                     |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Node.js 22, 24                               | Supported (CI matrix)                                                                                                      |
+| Modern browsers                              | Supported (verified in Chromium)                                                                                           |
+| Cloudflare Workers                           | `apixa`, `apixa/core`, `apixa/mocking*` (not `/node`) and `apixa/react/advanced`, run in `workerd` without `nodejs_compat` |
+| Vercel Edge Runtime                          | Same entries, run in `edge-runtime`                                                                                        |
+| React 18 / 19, Next.js 15 App Router, Vite 6 | Supported (packed consumers, production and development builds)                                                            |
+| TypeScript 5.5+                              | Declarations checked with 5.5.4 and the latest release, `Bundler` and `NodeNext` resolution                                |
+
+`apixa/mocking/node` reads the file system and is Node-only. Thrown errors keep `error.request`
+(including headers and body) readable but non-enumerable, so logging an error does not print
+credentials.
+
+## Core Principles
+
+- **Define once:** Keep API definitions in a single source of truth.
+- **Type-safe by design:** Infer request arguments and response types from definitions.
+- **Convention-driven:** Generate common resource operations where appropriate.
+- **Fully customizable:** Support custom endpoints and override generated behavior.
+- **Framework-agnostic:** Keep the core independent of UI frameworks and data-fetching libraries.
+- **Composable:** Allow additional capabilities through isolated subpaths.
+
+## Usage (implemented)
+
+Minimal resource — built-in CRUD is generated from `path`:
+
+```ts
+import { defineApi } from "apixa";
+const api = defineApi({
+  baseURL: "https://api.example.com",
+  headers: { Accept: "application/json" },
+  resources: { users: { path: "/users" } },
+});
+
+await api.users.getAll();
+await api.users.getById("123");
+await api.users.create({ name: "Ada", email: "ada@example.com" });
+await api.users.update("123", { name: "Ada Lovelace" });
+await api.users.delete("123");
+```
+
+Typed payloads use a Zustand-style **resource-only** state generic (no `type()` helper).
+`create` / `update` are derived from `entity` (`Omit<Entity,"id">` / `Partial<Entity>`).
+Root config (`baseURL`, `headers`, …) is typed by Core — not listed on `AppApi`:
+
+```ts
+import { defineApi } from "apixa";
+
+type User = { id: string; name: string; email: string };
+
+type AppApi = {
+  users: {
+    entity: User;
+  };
+};
+
+const api = defineApi<AppApi>()({
+  baseURL: "https://api.example.com",
+  headers: { Accept: "application/json", "X-Client": "dashboard" },
+  resources: {
+    users: {
+      path: "/users",
+      operations: {
+        getAll: { path: "/active" },
+        patch: { path: "/:id" },
+        archive: { kind: "write", method: "POST", path: "/:id/archive" },
+      },
+    },
+  },
+});
+```
+
+Operations return native `Promise<T>` (response data is unwrapped). A resource path generates 16
+builtins by default. The runtime resource config chooses paths and enabled methods; the optional
+generic supplies payload types. `operations` can disable a builtin with `false`, restore it with
+`true`, override it with a partial config, or define a custom operation with an explicit
+`kind: "read" | "write"`. Custom functions use `{ kind, run }`. HTTP methods must agree with
+the operation kind. `createMany` and
+`deleteMany` replace the former `bulkCreate` and `bulkDelete` names while retaining `/bulk` as
+their default wire path.
+
+```ts
+const api = defineApi<AppApi>()({
+  baseURL: "https://api.example.com",
+  resources: {
+    users: {
+      path: "/users",
+      readOnly: true,
+      operationGroups: { many: true },
+      operations: { create: true, getById: false },
+    },
+  },
+});
+// TypeScript exposes only the methods generated by these settings.
+```
+
+Set `defaultOperations: false` to start with no builtins, then enable individual operations or
+groups. `writeOnly: true` filters read defaults. Group precedence and all default wire conventions
+are documented in [docs/conventions.md](docs/conventions.md#selection-order).
+
+Pass `transport` to inject a custom HTTP implementation (used in tests). The default is Fetch, shipped inside Core.
+
+### Request reliability (implemented)
+
+Per-call cancel and timeout via `RequestOptions` (call → operation → resource → api). Abort → `AbortError`; timeout → `TimeoutError`.
+
+```ts
+const controller = new AbortController();
+await api.users.getAll({ signal: controller.signal, timeout: 5_000 });
+controller.abort();
+```
+
+Opt-in retries (default methods `GET` / `HEAD`; network errors, `408` / `429` / `5xx`):
+
+```ts
+const api = defineApi({
+  baseURL: "https://api.example.com",
+  timeout: 10_000,
+  retry: { retries: 2, baseDelayMs: 200 },
+  resources: { users: { path: "/users" } },
+});
+```
+
+Middleware hooks, request middleware, and response middleware run inside Core's request
+pipeline. See [`packages/core/README.md`](./packages/core/README.md) for the current API.
+
+See [`packages/core/README.md`](./packages/core/README.md) and CHANGELOG v0.7.0 migration notes.
+
+### Simple Mocking (implemented)
+
+Standalone, in-memory mock API from local datasets — no `defineApi()`, no network, no backend:
+
+```ts
+import { defineMockApi } from "apixa/mocking";
+
+const mockApi = defineMockApi({
+  resources: {
+    users: { type: "users-mock" },
+    products: { type: "products-mock", slice: 50, pagination: true },
+  },
+});
+
+const { data, total } = await mockApi.products.getAll({ page: 1, pageSize: 10 });
+```
+
+Typed data: `import { users, type User } from "apixa/mocking/datasets"`.
+
+Or mock individual resources of a Core client (register the included lazy dataset loader):
+
+```ts
+import { defineApi } from "apixa";
+import "apixa/mocking/register";
+
+const api = defineApi({
+  baseURL: "https://api.example.com",
+  resources: {
+    users: { path: "/users", mock: "users-mock", pagination: "page" },
+    payments: { path: "/payments" }, // real network
+  },
+});
+```
+
+See [`datasets/`](./datasets/) and [`packages/mocking`](./packages/mocking).
+
+See [`examples/next`](./examples/next) for the primary real-app playground (Next.js). Other frontends and a Node CLI live under [`examples/`](./examples/). Platform run scripts: [`scripts/README.md`](./scripts/README.md).
+
+## Vision
+
+Apixa is being designed around a small, extensible core that can grow into a broader API development ecosystem.
+
+**Implemented:** `defineApi()` with default-first CRUD (v0.2.0), resource-only `defineApi<T>()(config)` (v0.4.0), `@apixa/mocking` + datasets (v0.5.0), request reliability (v0.6.0), thin Core + plugin seams — path-param concat, `full` / middleware re-call, extension interfaces, structured error codes (v0.7.0).
+
+**Planned later:**
+
+- `crud<>()` preset.
+- Runtime schema validation hooks (no schema library in Core).
+- Live pagination, filtering, sorting, and search conventions.
+- Online dataset catalog (browse/download) — local datasets only today.
+- Other data-fetching integrations beyond the implemented TanStack Query package.
+- Browser and server packages.
+- OpenAPI interoperability.
+- Additional transports extracted from Core.
+
+These planned items are not currently implemented.
+
+## Design Philosophy
+
+Apixa Core will provide API definitions, type inference, and request execution without requiring React, TanStack Query, or a particular runtime framework.
+
+Integrations will build on the core rather than become dependencies of it.
+
+API methods are intended to return native promises, allowing them to work naturally with `async`/`await` and libraries such as TanStack Query.
+
+## Project Structure
+
+```text
+packages/
+  core/             # API definitions and execution
+  mocking/          # Local datasets and standalone mock APIs
+  react/            # Private React integration
+  internal/shared/  # Private, never published: framework-neutral integration helpers
+datasets/           # Version-controlled JSON fixtures
+examples/
+  next/             # Primary frontend playground (Next.js)
+  react-vite/ vue/ vanilla/ angular/ react-native/ basic/
+scripts/            # Frontend run scripts (macOS / Linux / Windows)
+tests/              # Vitest suite for core, mocking, and query
+docs/               # Living context, architecture, roadmap, ADRs
+versions/
+  v1.0.0/           # Active Query workstream
+```
+
+Planned later packages (not created yet): `transport-fetch`, `client`, `server`, `openapi`.
+
+## Documentation
+
+| Doc                                            | Purpose                                              |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| [docs/context.md](./docs/context.md)           | Project identity, principles, constraints            |
+| [docs/architecture.md](./docs/architecture.md) | Core shape and request flow                          |
+| [docs/roadmap.md](./docs/roadmap.md)           | Milestones and future phases                         |
+| [docs/conventions.md](./docs/conventions.md)   | How we build and document                            |
+| [versions/v1.0.0/](./versions/v1.0.0/)         | **Active coding contract** (scope, plan, acceptance) |
+
+## Project Status
+
+Apixa is in early development. Last shipped: **v0.11.0**. The v1.0.0 TanStack Query workstream is in progress. Core exposes `defineApi()` with default-first CRUD, reliability, re-callable middleware, and extension seams. Mocking augments Core for resource mocks.
+
+See [versions/v1.0.0/acceptance-criteria.md](./versions/v1.0.0/acceptance-criteria.md) for the active milestone checklist.
+
+## Author
+
+Created and maintained by **Abdalrahman bani younes** ([a2mby](https://github.com/a2mby)).
+
+## License
+
+Apixa is licensed under the MIT License. See [LICENSE](./LICENSE) for details.