apixa 0.0.0-stage → 0.1.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,258 @@
-# 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.
+
+## npm package
+
+The `apixa` package is prepared for publication but has not been published yet. After publication,
+install it with `npm install apixa`. Core has no framework dependency:
+
+```ts
+import { defineApi, defineApis } from "apixa";
+```
+
+Mocking is included under `apixa/mocking`; named datasets use `apixa/mocking/register` and
+`apixa/mocking/datasets`. For the optional React integration, install `react` and
+`@tanstack/react-query`, then import hooks from `apixa/react` and server-safe helpers from
+`apixa/react/advanced`. The existing scoped `@apixa/*` package entry points remain available
+for current consumers.
+
+## 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 optional packages.
+
+## 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 `@apixa/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
+  tanstack-query/   # Optional React Query integration
+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. `@apixa/core` exposes `defineApi()` with default-first CRUD, reliability, re-callable middleware, and extension seams. `@apixa/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.

package/dist/chunk-6ZX7GAWG.js

@@ -0,0 +1,10 @@
+import {
+  data_default
+} from "./chunk-QY5YMHHN.js";
+
+// packages/mocking/src/dataset-modules/comments.ts
+var comments = data_default;
+
+export {
+  comments
+};