@nano-app/frontend 0.3.6 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Serrano
+
+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

@@ -0,0 +1,195 @@
+# @nano-app/frontend
+
+Frontend of [nano-app](https://github.com/Nano-Nathan/nano-app) for Next.js apps: UI state in stores, and controllers whose methods the views use. Work in progress.
+
+## Quick start
+
+```bash
+pnpm add @nano-app/frontend
+```
+
+```ts
+// next.config.ts
+import { withNanoApp } from '@nano-app/frontend/next';
+
+export default withNanoApp({});
+```
+
+```tsx
+// app/layout.tsx
+import { NanoAppProvider } from '@nano-app/frontend';
+import type { ReactNode } from 'react';
+
+export default function RootLayout({ children }: { children: ReactNode }): ReactNode {
+  return (
+    <html lang="en">
+      <body>
+        <NanoAppProvider>{children}</NanoAppProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Stores
+
+A `src/stores/**/*.store.ts` is a store of UI state, named after its path (`src/stores/admin/users.store.ts` → `admin_users`). `withNanoApp` loads them at build time; `NanoAppProvider` gives each React tree its own copy. The `app` store is always there, empty when the app has no `app.store.ts`.
+
+```ts
+// src/stores/ui.store.ts
+export default { type: 'app', data: { isOpen: false } };
+```
+
+Each store reads and writes by path: `app.get('/drawer/isOpen')`, `app.set('/drawer/isOpen', true)`. A missing level reads as `undefined`, and `set` creates it.
+
+## Controllers and views
+
+A controller holds the methods; a view binds to one controller and gets its methods, the props and the stores. Several views can bind to the same controller.
+
+```ts
+// src/controllers/counter.controller.ts
+import { createController } from '@nano-app/frontend';
+
+export default createController(({ props, stores: { app } }) => ({
+  increment: () => app.set('/iCount', app.get('/iCount') + 1),
+}));
+```
+
+```tsx
+// src/components/Counter.tsx
+'use client';
+
+import counterController from '../controllers/counter.controller';
+
+export default counterController.bindView(({ stores: { app }, increment }) => (
+  <button onClick={increment}>{app.get('/iCount')}</button>
+));
+```
+
+- A file that calls `bindView` needs `'use client'`. A component without stores or methods is a plain React function and can stay a server component.
+- The view re-renders only when a store path it read changes.
+- A method named `props` or `stores` is hidden by the context of the same name.
+
+`extend` returns a new controller with your methods merged over its own: a method with the same name replaces the original, the others stay, and the original controller does not change. Its methods receive the same context (`props`, `stores`) as the controller's.
+
+```ts
+export default counterController.extend(({ stores: { app } }) => ({
+  reset: () => app.set('/iCount', 0),
+}));
+```
+
+## Backend
+
+A store of type `api` connects the app to a backend. The browser never talks to the backend: it calls `/api/<store>/...` on the Next server, and the proxy sends the request there.
+
+```ts
+// src/stores/backend.store.ts
+export default { type: 'api' };
+```
+
+```ts
+// proxy.ts, next to app/
+export { proxy } from '@nano-app/frontend/proxy';
+```
+
+The backend URL is read at runtime from `API_<STORE>_URL` (`backend` → `API_BACKEND_URL`, `admin/users.store.ts` → `API_ADMIN_USERS_URL`), on the server only: it never reaches the browser. The prefix goes away (`/api/backend/users/7?top=1` → `$API_BACKEND_URL/users/7?top=1`); a backend with a `basePath` puts it in the URL (`API_BACKEND_URL=http://backend:3000/api`).
+
+- The request keeps its method, headers, cookies and body, and the backend's answer comes back as is, `Set-Cookie` and redirects included.
+- Every `/api/<name>/...` goes to `API_<NAME>_URL`, and one without its variable answers 500 with the name of the variable to define. A request outside `/api/<name>` goes on to the app's own routes.
+
+### Reading and writing
+
+An `api` store reads and writes its backend, and keeps what it read. It also has its own state like any store (`get`, `set`, and `data` in its file), apart from what it read: UI state about that backend (a page, an order) can live next to it.
+
+```ts
+// src/controllers/users.controller.ts
+export default createController(({ stores: { backend } }) => ({
+  add: (sName: string) => backend.create('/users', { name: sName }),
+  rename: (iId: number, sName: string) => backend.update(`/users/${iId}`, { name: sName }),
+  remove: (iId: number) => backend.delete(`/users/${iId}`),
+}));
+```
+
+```tsx
+// src/components/Users.tsx
+export default usersController.bindView(({ stores: { backend }, rename }) => (
+  <ul>
+    {(backend.read('/users') ?? []).map(oUser => (
+      <li key={oUser.id} onClick={() => rename(oUser.id, 'Bruno')}>{oUser.name}</li>
+    ))}
+  </ul>
+));
+```
+
+- `read(path, query?)` returns the `result` it keeps for that path and query, `undefined` until it arrives. It works in the render: the first read, or a read after its entity changed, asks the backend (`GET`, or `QUERY` with the query as JSON body), and the view renders again when the answer comes. Each path and query is asked once per change of its entity.
+- The entity is the first segment of the path (`/users/7` → `/users`). `create` (`POST <path>`), `update` (`PUT <path>`) and `delete` (`DELETE <path>`) return the `ApiResponse`, and when it comes back every read of the entity asks again the next time it renders, whatever its query. Other entities keep what they have.
+- On the server (the first HTML that Next renders) `read` asks nothing and returns `undefined`: the browser asks when it hydrates.
+- `busy` counts the requests in progress (`backend.busy ? 'Loading…' : …`).
+- A read keeps the `result` of its answer, `undefined` when it failed, and is not asked again until a write on its entity. A request that fails (no answer, or not JSON) rejects: the errors module will show it.
+- What another user changes is seen after a write on the same entity.
+- Every path and query read stays kept while the page is open.
+
+To ask only when the user stops typing, keep the text in the `app` store and copy it to the query after a pause:
+
+```ts
+let oTimer: ReturnType<typeof setTimeout>;
+export default createController(({ stores: { app } }) => ({
+  type: (sText: string) => {
+    app.set('/search/text', sText);
+    clearTimeout(oTimer);
+    oTimer = setTimeout(() => app.set('/search/applied', sText), 300);
+  },
+}));
+// The view reads backend.read('/users', { filter: { name: { contains: app.get('/search/applied') } } })
+```
+
+### Headers per backend
+
+A backend that asks for a key (`x-api-key`) gets it from the proxy. The store names the header and the variable that holds its value, never the value itself, since store files reach the browser:
+
+```ts
+// src/stores/payments.store.ts
+export default { type: 'api', headers: { 'x-api-key': 'STRIPE_KEY' } };
+```
+
+The proxy sends `x-api-key` with the value of `API_STRIPE_KEY_HEADER` (the name in upper case) on every request to that store; a missing variable answers 500 with its name.
+
+- A store header wins over a browser header with the same name: the browser cannot replace or guess the key.
+- The user's own credentials (the session cookie, `Authorization`) still go as the browser sends them. Do not declare a header the user needs in the store, or every user goes with the store's value.
+- Without a `matcher`, Next runs the proxy on every request; to skip the rest, add `export const config = { matcher: '/api/:path*' };` to `proxy.ts` (Next reads it only when it is written there).
+
+### With a proxy of your own
+
+Next takes one `proxy.ts`. To keep yours, call nano-app's from it for `/api` and include `/api/:path*` in your `matcher`:
+
+```ts
+// proxy.ts
+import { NextResponse } from 'next/server';
+import { proxy as nanoProxy } from '@nano-app/frontend/proxy';
+import type { NextRequest } from 'next/server';
+
+export function proxy(oReq: NextRequest) {
+  if (oReq.nextUrl.pathname.startsWith('/api/')) return nanoProxy(oReq);
+
+  // Your own logic
+  return NextResponse.next();
+}
+
+export const config = { matcher: ['/api/:path*', '/dashboard/:path*'] };
+```
+
+## Test app
+
+`tests/app` is a Next app that uses the package from the workspace:
+
+```bash
+pnpm --filter @nano-app/frontend build
+pnpm --filter nano-frontend-test-app build
+pnpm --filter nano-frontend-test-app start   # http://localhost:3100
+```
+
+The `Users` component reads and writes `/users` of the `backend` store: point it at any backend that answers `GET`, `POST`, `PUT` and `DELETE` on `/users` with an `ApiResponse`, and give it the key its store declares:
+
+```bash
+API_BACKEND_URL=http://localhost:3000 API_BACKEND_KEY_HEADER=dev pnpm --filter nano-frontend-test-app start
+```

package/build/core/const.d.ts

@@ -0,0 +1,4 @@
+//#region ../core/const.d.ts
+/** Name of the app: the backend's main plugin and the frontend's store of UI state, always present */
+export declare const APP_NAME = "app";
+//#endregion

package/build/core/const.js

@@ -0,0 +1,9 @@
+//#region ../core/const.ts
+/** Whether the code runs on the server, where Next renders each component once for the HTML */
+const IS_SERVER = typeof window === "undefined";
+/** Env var that carries the stores to the bundle. Read as `process.env.NANO_APP_STORES`, literal */
+const STORES_ENV = "NANO_APP_STORES";
+/** Error of a component outside the provider */
+const MISSING_PROVIDER = "[nano-app] [ERROR] A component has no stores. Wrap the root layout with NanoAppProvider.";
+//#endregion
+export { IS_SERVER, MISSING_PROVIDER, STORES_ENV };

package/build/core/loader/FileLoader.js

@@ -0,0 +1,38 @@
+import Validator from "./Validator.js";
+import FileReader from "./FileReader.js";
+import Formatter from "../utils/Formatter.js";
+import { glob } from "glob";
+//#region ../core/loader/FileLoader.ts
+/** Finds, loads and validates the consumer's files */
+var FileLoader = class {
+	/**
+	* 1. Validates a `.prisma` file.
+	* 2. Loads a generated Prisma client module (`client.ts`, or `client.js`)
+	*/
+	static async findPrismaClient(sClientPath, sSchemaPath) {
+		const sContent = FileReader.loadSchema(sSchemaPath);
+		if (!Validator.validateUnique(sContent, "prisma", sSchemaPath)) throw new Error(`[nano-app] [ERROR] ${sSchemaPath} is not a valid Prisma schema.`);
+		try {
+			return (await FileReader.loadModule(sClientPath))?.PrismaClient;
+		} catch (oError) {
+			throw new Error(`[nano-app] [ERROR] The Prisma client ${sClientPath} could not be loaded: ${Formatter.error(oError)}`);
+		}
+	}
+	/** Finds `*.route.ts` (or built `.js`) files and returns `{ [subPath]: defaultExport }` */
+	static async findMany({ extension, sourceDir }) {
+		const sSrcDir = (sourceDir ?? `src/${extension}s`).replace(/^\.\//, "").replace(/\/$/, "");
+		const aFilePaths = await glob(`${sSrcDir}/**/*.${extension}.{ts,js}`, {
+			posix: true,
+			ignore: "**/*.d.ts"
+		});
+		const oEntries = {};
+		for (const sFilePath of aFilePaths) {
+			const sFileSubPath = sFilePath.slice(sSrcDir.length).replace(new RegExp(`\\.${extension}\\.(ts|js)$`), "");
+			const sKey = extension === "store" ? sFileSubPath.slice(1).replaceAll("/", "_") : sFileSubPath;
+			oEntries[sKey] = await FileReader.loadModule(sFilePath, { default: true });
+		}
+		return Validator.validate(oEntries, extension);
+	}
+};
+//#endregion
+export { FileLoader as default };

package/build/core/loader/FileReader.js

@@ -0,0 +1,30 @@
+import { isAbsolute, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { createJiti } from "jiti";
+//#region ../core/loader/FileReader.ts
+/** Reads and loads files from disk, resolved from `cwd` */
+var FileReader = class {
+	static oJiti = createJiti(import.meta.url, { nativeModules: ["@prisma/client"] });
+	/** Loads a module via jiti */
+	static async loadModule(sFilePath, oOptions = {}) {
+		return await this.oJiti.import(this.getAbsolutePath(sFilePath), oOptions);
+	}
+	/** Reads the contents of a file */
+	static loadFile(sFilePath) {
+		const sContent = readFileSync(this.getAbsolutePath(sFilePath), "utf-8");
+		if (!sContent) throw new Error(`[nano-app] [ERROR] The file ${sFilePath} does not have valid content.`);
+		return sContent;
+	}
+	/** Reads a Prisma schema without its `//` comments */
+	static loadSchema(sFilePath) {
+		return this.loadFile(sFilePath).replace(/\/\/.*$/gm, "");
+	}
+	/** Resolves the absolute path of a file */
+	static getAbsolutePath(sFilePath) {
+		const sAbsolutePath = isAbsolute(sFilePath) ? sFilePath : resolve(process.cwd(), sFilePath);
+		if (!existsSync(sAbsolutePath)) throw new Error(`[nano-app] [ERROR] ${sFilePath} not found.`);
+		return sAbsolutePath;
+	}
+};
+//#endregion
+export { FileReader as default };

package/build/core/loader/Validator.js

@@ -0,0 +1,70 @@
+//#region ../core/loader/Validator.ts
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"DELETE",
+	"QUERY"
+];
+const STORE_TYPES = ["app", "api"];
+/** Checks the consumer's files: invalid ones are warned about and discarded */
+var Validator = class Validator {
+	static oValidators = {
+		route: () => this.isRoute,
+		prisma: () => this.isPrisma,
+		store: () => this.isStore
+	};
+	/** Warns about an invalid file and returns `false`, to discard it */
+	static warn(sFilePath, sMessage) {
+		console.warn(`[nano-app] [WARNING] ${sFilePath}: ${sMessage}`);
+		return false;
+	}
+	/** Checks that the default export is an object */
+	static isObject(oEntry, sFilePath) {
+		if (oEntry && typeof oEntry === "object") return true;
+		return Validator.warn(sFilePath, "the default export is not an object.");
+	}
+	/**
+	* Type guard for a `*.route.ts` entry.
+	*/
+	static isRoute(oEntry, sFilePath) {
+		if (!Validator.isObject(oEntry, sFilePath)) return false;
+		const oRoute = oEntry;
+		if (oRoute.expression && typeof oRoute.expression !== "string") return Validator.warn(sFilePath, "\"expression\" must be a string.");
+		for (const sMethod of HTTP_METHODS) if (oRoute[sMethod] && typeof oRoute[sMethod] !== "function") return Validator.warn(sFilePath, `"${String(sMethod)}" must be a function.`);
+		if (!HTTP_METHODS.some((sMethod) => oRoute[sMethod])) return Validator.warn(sFilePath, "defines no HTTP method.");
+		return true;
+	}
+	/** Type guard for a `*.store.ts` entry */
+	static isStore(oEntry, sFilePath) {
+		if (!Validator.isObject(oEntry, sFilePath)) return false;
+		if (!STORE_TYPES.includes(oEntry.type)) return Validator.warn(sFilePath, `its type must be "app" or "api".`);
+		if (oEntry.data !== void 0 && (!oEntry.data || typeof oEntry.data !== "object")) return Validator.warn(sFilePath, "\"data\" must be an object.");
+		if (oEntry.headers !== void 0 && (!Validator.isObject(oEntry.headers, sFilePath) || Object.values(oEntry.headers).some((sValue) => typeof sValue !== "string"))) return Validator.warn(sFilePath, "\"headers\" must be an object of strings.");
+		return true;
+	}
+	/**
+	* Type guard for a `.prisma` entry: the contents of the file, without comments.
+	*/
+	static isPrisma(oEntry, sFilePath) {
+		if (typeof oEntry !== "string") return Validator.warn(sFilePath, "the contents are not a string.");
+		const sProvider = oEntry.match(/datasource\s+\w+\s*\{[^}]*provider\s*=\s*["']([^"']+)["']/s)?.[1];
+		if (sProvider !== "postgresql") return Validator.warn(sFilePath, `the datasource provider must be "postgresql"${sProvider ? `, not "${sProvider}"` : ""}.`);
+		return true;
+	}
+	/** Validates a full map of entries and returns only the valid ones */
+	static validate(oEntries, sExtension) {
+		const oValid = {};
+		for (const [sFilePath, oEntry] of Object.entries(oEntries)) {
+			const oValidated = this.validateUnique(oEntry, sExtension, sFilePath);
+			if (oValidated !== void 0) oValid[sFilePath] = oValidated;
+		}
+		return oValid;
+	}
+	/** Validates one entry: returns it when valid, `undefined` otherwise */
+	static validateUnique(oEntry, sExtension, sFilePath = "") {
+		return this.oValidators[sExtension]?.()(oEntry, sFilePath) ? oEntry : void 0;
+	}
+};
+//#endregion
+export { Validator as default };

package/build/core/types/objects.d.ts

@@ -0,0 +1,4 @@
+//#region ../core/types/objects.d.ts
+/** Generic object */
+export type NanoObject<T = any> = Record<string, T>;
+//#endregion

package/build/core/utils/Formatter.js

@@ -0,0 +1,14 @@
+//#region ../core/utils/Formatter.ts
+/** Formats values for logs and messages */
+var Formatter = class {
+	/** Message of anything thrown: its `message` when it has one, else the value itself */
+	static error(oError) {
+		return String(oError?.message ?? oError);
+	}
+	/** Formats a date for the request log, in UTC: `2026-10-19 12:03:10` */
+	static logDate(oDate = /* @__PURE__ */ new Date()) {
+		return oDate.toISOString().slice(0, 19).replace("T", " ");
+	}
+};
+//#endregion
+export { Formatter as default };

package/build/creators/createController.d.ts

@@ -0,0 +1,6 @@
+import { NanoObject } from "../core/types/objects.js";
+import { ComponentContext, Controller } from "../types/component.js";
+//#region src/creators/createController.d.ts
+/** Creates a controller: methods on the stores and the props, for the views bound to it */
+export default function createController<M extends NanoObject>(fnMethods: (context: ComponentContext) => M): Controller<M>;
+//#endregion

package/build/creators/createController.js

@@ -0,0 +1,27 @@
+"use client";
+import { IS_SERVER } from "../core/const.js";
+import { useStores } from "../react/NanoAppProvider.js";
+import { enableStaticRendering, observer } from "mobx-react-lite";
+//#region src/creators/createController.ts
+enableStaticRendering(IS_SERVER);
+/** Creates a controller: methods on the stores and the props, for the views bound to it */
+function createController(fnMethods) {
+	return {
+		bindView: (fnView) => observer((oProps) => {
+			const oContext = {
+				props: oProps,
+				stores: useStores()
+			};
+			return fnView({
+				...fnMethods(oContext),
+				...oContext
+			});
+		}),
+		extend: (fnExtension) => createController((oContext) => ({
+			...fnMethods(oContext),
+			...fnExtension(oContext)
+		}))
+	};
+}
+//#endregion
+export { createController as default };

package/build/creators/createStores.js

@@ -0,0 +1,15 @@
+import Store from "../stores/Store.js";
+import ApiStore from "../stores/ApiStore.js";
+//#region src/creators/createStores.ts
+/** Stores of one React tree, from the ones `withNanoApp` inlined at build time */
+function createStores() {
+	const oFiles = JSON.parse(process.env.NANO_APP_STORES ?? "{}");
+	return {
+		...Object.fromEntries(Object.entries(oFiles).map(([sName, oFile]) => {
+			return [sName, oFile.type === "api" ? new ApiStore(sName, oFile.data) : new Store(oFile.data)];
+		})),
+		["app"]: new Store(oFiles["app"]?.data)
+	};
+}
+//#endregion
+export { createStores as default };

package/build/index.d.ts

@@ -0,0 +1,4 @@
+import { NanoAppProvider } from "./react/NanoAppProvider.js";
+import { ComponentContext, ComponentProps, Controller, View } from "./types/component.js";
+import createController from "./creators/createController.js";
+export { type ComponentContext, type ComponentProps, type Controller, NanoAppProvider, type View, createController };

package/build/index.js

@@ -0,0 +1,3 @@
+import { NanoAppProvider } from "./react/NanoAppProvider.js";
+import createController from "./creators/createController.js";
+export { NanoAppProvider, createController };

package/build/next.d.ts

@@ -0,0 +1,8 @@
+import { NextConfig } from "next";
+//#region src/next.d.ts
+/**
+ * Wraps the app's Next config: loads its stores while Next reads `next.config.ts`, before compiling.
+ * Node only: never import it from the app's components.
+ */
+export declare function withNanoApp(oNextConfig?: NextConfig): () => Promise<NextConfig>;
+//#endregion

package/build/next.js

@@ -0,0 +1,21 @@
+import { STORES_ENV } from "./core/const.js";
+import FileLoader from "./core/loader/FileLoader.js";
+//#region src/next.ts
+/**
+* Wraps the app's Next config: loads its stores while Next reads `next.config.ts`, before compiling.
+* Node only: never import it from the app's components.
+*/
+function withNanoApp(oNextConfig = {}) {
+	return async () => {
+		const oStores = await FileLoader.findMany({ extension: "store" });
+		return {
+			...oNextConfig,
+			env: {
+				...oNextConfig.env,
+				[STORES_ENV]: JSON.stringify(oStores)
+			}
+		};
+	};
+}
+//#endregion
+export { withNanoApp };

package/build/proxy.d.ts

@@ -0,0 +1,5 @@
+import { NextRequest } from "next/server";
+//#region src/proxy.d.ts
+/** Sends `/api/<store>/<path>` to the backend of `<store>`, in `API_<STORE>_URL`, with its headers */
+export declare function proxy(oReq: NextRequest): Promise<Response>;
+//#endregion

package/build/proxy.js

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+//#region src/proxy.ts
+/** Sends `/api/<store>/<path>` to the backend of `<store>`, in `API_<STORE>_URL`, with its headers */
+async function proxy(oReq) {
+	const [, sPrefix, sName, ...aPath] = oReq.nextUrl.pathname.split("/");
+	if (sPrefix !== "api" || !sName) return NextResponse.next();
+	const oFiles = JSON.parse(process.env.NANO_APP_STORES ?? "{}");
+	const sUrlEnv = `API_${sName.toUpperCase()}_URL`;
+	const aHeaders = Object.entries(oFiles[sName]?.headers ?? {}).map(([sHeader, sValue]) => [sHeader, `API_${sValue.toUpperCase()}_HEADER`]);
+	const sMissing = [sUrlEnv, ...aHeaders.map(([, sEnvName]) => sEnvName)].find((sEnvName) => !process.env[sEnvName]);
+	if (sMissing) return NextResponse.json({
+		success: false,
+		message: `[nano-app] [ERROR] The store "${sName}" needs the ${sMissing} environment variable. Define it.`
+	}, { status: 500 });
+	const oHeaders = new Headers(oReq.headers);
+	for (const [sHeader, sEnvName] of aHeaders) oHeaders.set(sHeader, process.env[sEnvName] ?? "");
+	const sTarget = `${process.env[sUrlEnv]}/${aPath.join("/")}${oReq.nextUrl.search}`;
+	const oRes = await fetch(new Request(sTarget, oReq), {
+		headers: oHeaders,
+		redirect: "manual"
+	});
+	return new Response(oRes.body, oRes);
+}
+//#endregion
+export { proxy };

package/build/react/NanoAppProvider.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from "react";
+//#region src/react/NanoAppProvider.d.ts
+/** Root of the app's React tree: wraps the root layout and gives the tree its own stores */
+export declare function NanoAppProvider({ children }: {
+  children: ReactNode;
+}): ReactNode;
+//#endregion

package/build/react/NanoAppProvider.js

@@ -0,0 +1,25 @@
+"use client";
+import { MISSING_PROVIDER } from "../core/const.js";
+import createStores from "../creators/createStores.js";
+import { createContext, use, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/NanoAppProvider.tsx
+/** Stores of the tree, read by the components */
+const StoreContext = createContext(null);
+/** Root of the app's React tree: wraps the root layout and gives the tree its own stores */
+function NanoAppProvider({ children }) {
+	const oStoresRef = useRef(null);
+	oStoresRef.current ??= createStores();
+	return /* @__PURE__ */ jsx(StoreContext, {
+		value: oStoresRef.current,
+		children
+	});
+}
+/** Stores of the tree; fails outside the provider */
+function useStores() {
+	const oStores = use(StoreContext);
+	if (!oStores) throw new Error(MISSING_PROVIDER);
+	return oStores;
+}
+//#endregion
+export { NanoAppProvider, useStores };

package/build/stores/ApiStore.js

@@ -0,0 +1,81 @@
+import { IS_SERVER } from "../core/const.js";
+import Store from "./Store.js";
+import { observable, runInAction } from "mobx";
+//#region src/stores/ApiStore.ts
+/**
+* Backend data of an `api` store, through its proxy (`/api/<name>/...`), by path and query.
+* Its own state (`get`/`set`) is the one of a `Store`; what it read stays apart.
+*/
+var ApiStore = class ApiStore extends Store {
+	sName;
+	oCache = observable({
+		iBusy: 0,
+		oResults: {},
+		oVersions: {}
+	});
+	oRead = {};
+	/** Store of the backend `API_<NAME>_URL`, with the initial data of its file */
+	constructor(sName, oData) {
+		super(oData);
+		this.sName = sName;
+	}
+	/** Requests in progress */
+	get busy() {
+		return this.oCache.iBusy;
+	}
+	/** Result at a path: from local, asked to the backend when never read or its entity changed */
+	read(sPath, oQuery) {
+		if (IS_SERVER) return void 0;
+		const sKey = oQuery ? `${sPath}?${JSON.stringify(oQuery)}` : sPath;
+		const iVersion = this.oCache.oVersions[ApiStore.entity(sPath)] ?? 0;
+		if (this.oRead[sKey] !== iVersion) {
+			this.oRead[sKey] = iVersion;
+			const oInit = oQuery ? {
+				method: "QUERY",
+				body: JSON.stringify(oQuery)
+			} : { method: "GET" };
+			queueMicrotask(() => this.request(sPath, oInit).then((oResponse) => runInAction(() => this.oCache.oResults[sKey] = oResponse.result)));
+		}
+		return this.oCache.oResults[sKey];
+	}
+	/** `POST <path>` */
+	create(sPath, oBody) {
+		return this.write("POST", sPath, oBody);
+	}
+	/** `PUT <path>` */
+	update(sPath, oBody) {
+		return this.write("PUT", sPath, oBody);
+	}
+	/** `DELETE <path>` */
+	delete(sPath) {
+		return this.write("DELETE", sPath);
+	}
+	/** Sends a write and changes the version of its entity when the answer comes back */
+	write(sMethod, sPath, oBody) {
+		return this.request(sPath, {
+			method: sMethod,
+			body: JSON.stringify(oBody)
+		}).finally(() => runInAction(() => {
+			const sEntity = ApiStore.entity(sPath);
+			this.oCache.oVersions[sEntity] = (this.oCache.oVersions[sEntity] ?? 0) + 1;
+		}));
+	}
+	/** Sends a request to the proxy and returns its JSON answer, counting it as busy */
+	async request(sPath, oInit) {
+		runInAction(() => this.oCache.iBusy++);
+		try {
+			return await (await fetch(`/api/${this.sName}${sPath}`, {
+				...oInit,
+				headers: { "content-type": "application/json" }
+			})).json();
+		} finally {
+			runInAction(() => this.oCache.iBusy--);
+		}
+	}
+	/** Entity of a path: its first segment (`/users/7` → `/users`) */
+	static entity(sPath) {
+		return `/${sPath.split("/").filter(Boolean)[0] ?? ""}`;
+	}
+};
+//#endregion
+export { ApiStore as default };

package/build/stores/Store.d.ts

@@ -0,0 +1,15 @@
+import { NanoObject } from "../core/types/objects.js";
+//#region src/stores/Store.d.ts
+/** State of one store, read and written by path (`/drawer/isOpen`) */
+export default class Store {
+  private oState;
+  /** Makes the store's initial data observable, so reads are tracked and writes notify them */
+  constructor(oData?: NanoObject);
+  /** Value at a path: an object comes back observable, so reading its fields stays tracked */
+  get(sPath: string): any;
+  /** Writes a value at a path, creating the levels that are missing */
+  set(sPath: string, oValue: unknown): void;
+  /** Keys of a path, with or without the leading slash */
+  private static keys;
+}
+//#endregion