@nano-app/frontend 0.4.0 → 0.5.0

package/README.md

@@ -70,6 +70,14 @@ export default counterController.bindView(({ stores: { app }, increment }) => (
 - 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.
@@ -91,7 +99,7 @@ The backend URL is read at runtime from `API_<STORE>_URL` (`backend` → `API_BA
 
 ### Reading and writing
 
-An `api` store has no `get` or `set`: it reads and writes its backend, and keeps what it read.
+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

package/build/creators/createController.js

@@ -6,16 +6,22 @@ import { enableStaticRendering, observer } from "mobx-react-lite";
 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({
+	return {
+		bindView: (fnView) => observer((oProps) => {
+			const oContext = {
+				props: oProps,
+				stores: useStores()
+			};
+			return fnView({
+				...fnMethods(oContext),
+				...oContext
+			});
+		}),
+		extend: (fnExtension) => createController((oContext) => ({
 			...fnMethods(oContext),
-			...oContext
-		});
-	}) };
+			...fnExtension(oContext)
+		}))
+	};
 }
 //#endregion
 export { createController as default };

package/build/creators/createStores.js

@@ -1,12 +1,12 @@
-import ApiStore from "../stores/ApiStore.js";
 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) : new Store(oFile.data)];
+			return [sName, oFile.type === "api" ? new ApiStore(sName, oFile.data) : new Store(oFile.data)];
 		})),
 		["app"]: new Store(oFiles["app"]?.data)
 	};

package/build/stores/ApiStore.js

@@ -1,37 +1,42 @@
 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 */
-var ApiStore = class ApiStore {
+/**
+* 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;
-	oState = observable({
+	oCache = observable({
 		iBusy: 0,
 		oResults: {},
 		oVersions: {}
 	});
 	oRead = {};
-	/** Store of the backend `API_<NAME>_URL` */
-	constructor(sName) {
+	/** 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.oState.iBusy;
+		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.oState.oVersions[ApiStore.entity(sPath)] ?? 0;
+		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.oState.oResults[sKey] = oResponse.result)));
+			queueMicrotask(() => this.request(sPath, oInit).then((oResponse) => runInAction(() => this.oCache.oResults[sKey] = oResponse.result)));
 		}
-		return this.oState.oResults[sKey];
+		return this.oCache.oResults[sKey];
 	}
 	/** `POST <path>` */
 	create(sPath, oBody) {
@@ -52,19 +57,19 @@ var ApiStore = class ApiStore {
 			body: JSON.stringify(oBody)
 		}).finally(() => runInAction(() => {
 			const sEntity = ApiStore.entity(sPath);
-			this.oState.oVersions[sEntity] = (this.oState.oVersions[sEntity] ?? 0) + 1;
+			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.oState.iBusy++);
+		runInAction(() => this.oCache.iBusy++);
 		try {
 			return await (await fetch(`/api/${this.sName}${sPath}`, {
 				...oInit,
 				headers: { "content-type": "application/json" }
 			})).json();
 		} finally {
-			runInAction(() => this.oState.iBusy--);
+			runInAction(() => this.oCache.iBusy--);
 		}
 	}
 	/** Entity of a path: its first segment (`/users/7` → `/users`) */

package/build/types/component.d.ts

@@ -15,5 +15,7 @@ export type View<M extends NanoObject> = (params: Omit<M, keyof ComponentContext
 export type Controller<M extends NanoObject> = {
   /** Creates a component that renders the view with the controller's methods */
   bindView(view: View<M>): (props: ComponentProps) => ReactNode;
+  /** Creates a controller with these methods merged over its own: a method with the same name wins */
+  extend<E extends NanoObject>(methods: (context: ComponentContext) => E): Controller<Omit<M, keyof E> & E>;
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/frontend",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React provider for Next.js apps on top of @nano-app/backend",
   "type": "module",
   "exports": {