@atscript/db-client 0.1.43 → 0.1.44

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">@atscript/db-client</h1>
 
 <p align="center">
-  Browser-compatible HTTP client for <code>@atscript/moost-db</code> REST endpoints.
+  HTTP client for <code>@atscript/moost-db</code> REST endpoints.
 </p>
 
 <p align="center">
@@ -14,7 +14,9 @@
 
 ---
 
-Type-safe HTTP client that mirrors the server-side `AtscriptDbTable` API over REST. Works in browsers, Node.js, and any runtime with `fetch`. Supports the full query surface — filters, sorting, pagination, relation loading, text search, and aggregation.
+Type-safe HTTP client that mirrors moost-db controller endpoints. Works in browsers, Node.js, and any runtime with `fetch`. Each method maps 1:1 to a controller endpoint — filters, sorting, pagination, relation loading, text search, and aggregation are all supported through typed query controls.
+
+In SSR environments, Moost's `fetch` automatically routes local requests to handlers in-process, so the same `Client` instance works on both server and browser.
 
 ## Installation
 
@@ -32,27 +34,39 @@ const users = new Client<typeof User>("/api/users", {
   baseUrl: "https://api.example.com",
 });
 
-// Query
-const active = await users.findMany({ filter: { status: "active" } });
-const user = await users.findById("abc-123");
+// Query                            → GET /query
+const active = await users.query({ filter: { status: "active" } });
+
+// Get one                          → GET /one/:id
+const user = await users.one("abc-123");
+
+// Insert                           → POST /
+const { insertedId } = await users.insert({ name: "Alice" });
+
+// Update                           → PATCH /
+await users.update({ id: insertedId, role: "admin" });
+
+// Remove                           → DELETE /:id
+await users.remove(insertedId);
+
+// Count                            → GET /query ($count)
+const total = await users.count();
 
-// Write
-const { insertedId } = await users.insertOne({ name: "Alice" });
-await users.updateOne({ id: insertedId, role: "admin" });
-await users.deleteOne(insertedId);
+// Paginate                         → GET /pages
+const page = await users.pages({ filter: { active: true } }, 1, 20);
 
-// Metadata
+// Metadata                         → GET /meta
 const meta = await users.meta();
 ```
 
 ## Features
 
-- **Full CRUD** — `findMany`, `findOne`, `findById`, `count`, `pages`, `insertOne`, `insertMany`, `updateOne`, `bulkUpdate`, `replaceOne`, `bulkReplace`, `deleteOne`
-- **URL query syntax** — filtering, sorting, pagination, field selection, relation loading via `$with`
-- **Search** — full-text (`search()`) and vector search via query controls
-- **Aggregation** — `$groupBy` with aggregate functions
+- **Typed queries** — filter keys, sort fields, `$with` relation names, and primary keys are type-checked against the Atscript model
+- **Full CRUD** — `query`, `count`, `pages`, `one`, `insert`, `update`, `replace`, `remove`
+- **Aggregation** — typed `$groupBy` dimensions and measures with inferred result types
+- **Search** — full-text and vector search via query controls
+- **Client-side validation** — validates writes against the Atscript schema before sending
 - **Error handling** — `ClientError` with structured validation errors
-- **SSR isomorphism** — `DbInterface<T>` shared between server `AtscriptDbTable` and client `Client`
 - **Configurable** — custom `fetch`, static or async headers, base URL
 
 ## Documentation

package/dist/index.cjs

@@ -20,15 +20,24 @@ var ClientError = class extends Error {
 //#endregion
 //#region src/client.ts
 /**
-* Browser-compatible HTTP client for moost-db REST endpoints.
+* HTTP client for moost-db REST endpoints.
 *
-* Two usage modes (same class, different generic):
-* ```typescript
-* // Untyped — broad Record<string, unknown> typing
-* const users = new Client('/db/tables/users')
+* Each method maps 1:1 to a controller endpoint:
+* - `query()` → `GET /query`
+* - `count()` → `GET /query` with `$count`
+* - `aggregate()` → `GET /query` with `$groupBy`
+* - `pages()` → `GET /pages`
+* - `one()`   → `GET /one/:id` or `GET /one?compositeKeys`
+* - `insert()`  → `POST /`
+* - `update()`  → `PATCH /`
+* - `replace()` → `PUT /`
+* - `remove()`  → `DELETE /:id` or `DELETE /?compositeKeys`
+* - `meta()`  → `GET /meta`
 *
-* // Type-safe — Atscript type as generic parameter
-* const users = new Client<typeof User>('/db/tables/users')
+* ```typescript
+* const users = new Client<typeof User>('/api/users')
+* const all = await users.query()
+* const page = await users.pages({ filter: { active: true } }, 1, 20)
 * ```
 */
 var Client = class {
@@ -37,124 +46,127 @@ var Client = class {
 	_fetch;
 	_headers;
 	_metaPromise;
+	_validatorPromise;
 	constructor(path, opts) {
 		this._path = path.endsWith("/") ? path.slice(0, -1) : path;
 		this._baseUrl = opts?.baseUrl ?? "";
 		this._fetch = opts?.fetch ?? globalThis.fetch.bind(globalThis);
 		this._headers = opts?.headers;
 	}
-	async findOne(query) {
-		const controls = {
-			...query?.controls,
-			$limit: 1
-		};
-		return (await this._get("query", {
-			...query,
-			controls
-		}))[0] ?? null;
-	}
-	async findMany(query) {
+	/**
+	* `GET /query` — query records with typed filter, sort, select, and relations.
+	*/
+	async query(query) {
 		return this._get("query", query);
 	}
-	async findById(id, query) {
-		if (id !== null && typeof id === "object") {
-			const params = this._idToParams(id);
-			if (query?.controls) {
-				const controlStr = (0, _uniqu_url_builder.buildUrl)({ controls: query.controls });
-				if (controlStr) for (const [k, v] of new URLSearchParams(controlStr)) params.set(k, v);
-			}
-			const qs = params.toString();
-			try {
-				return await this._request("GET", `one${qs ? `?${qs}` : ""}`);
-			} catch (e) {
-				if (e instanceof ClientError && e.status === 404) return null;
-				throw e;
-			}
-		}
-		const controlStr = query?.controls ? (0, _uniqu_url_builder.buildUrl)({ controls: query.controls }) : "";
-		try {
-			return await this._request("GET", `one/${encodeURIComponent(String(id))}${controlStr ? `?${controlStr}` : ""}`);
-		} catch (e) {
-			if (e instanceof ClientError && e.status === 404) return null;
-			throw e;
-		}
-	}
+	/**
+	* `GET /query` with `$count: true` — returns record count.
+	*/
 	async count(query) {
-		const controls = {
-			...query?.controls,
-			$count: true
-		};
 		return this._get("query", {
 			...query,
-			controls
+			controls: { $count: true }
 		});
 	}
-	async findManyWithCount(query) {
-		const controls = query?.controls ?? {};
-		const limit = controls.$limit || 1e3;
-		const skip = controls.$skip || 0;
-		const page = Math.floor(skip / limit) + 1;
-		const result = await this._get("pages", {
+	/**
+	* `GET /query` with `$groupBy` — aggregate query with typed dimension/measure fields.
+	*/
+	async aggregate(query) {
+		return this._get("query", query);
+	}
+	/**
+	* `GET /pages` — paginated query with typed filter and relations.
+	*/
+	async pages(query, page = 1, size = 10) {
+		return this._get("pages", {
 			...query,
 			controls: {
-				...controls,
+				...query?.controls,
 				$page: page,
-				$size: limit
+				$size: size
 			}
 		});
-		return {
-			data: result.data,
-			count: result.count
-		};
-	}
-	async pages(query) {
-		return this._get("pages", query);
-	}
-	async search(text, query, indexName) {
-		const controls = {
-			...query?.controls,
-			$search: text
-		};
-		if (indexName) controls.$index = indexName;
-		return this._get("query", {
-			...query,
-			controls
-		});
 	}
-	async aggregate(query) {
-		return this._get("query", query);
-	}
-	async insertOne(data) {
-		return this._request("POST", "", data);
+	/**
+	* `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
+	*
+	* Returns `null` on 404.
+	*/
+	async one(id, query) {
+		const controlStr = query?.controls ? (0, _uniqu_url_builder.buildUrl)({ controls: query.controls }) : "";
+		if (id !== null && typeof id === "object") {
+			const params = this._idToParams(id);
+			if (controlStr) for (const [k, v] of new URLSearchParams(controlStr)) params.set(k, v);
+			const qs = params.toString();
+			return this._getOrNull(`one${qs ? `?${qs}` : ""}`);
+		}
+		return this._getOrNull(`one/${encodeURIComponent(String(id))}${controlStr ? `?${controlStr}` : ""}`);
 	}
-	async insertMany(data) {
+	async insert(data) {
+		await this._validateData(data, "insert");
 		return this._request("POST", "", data);
 	}
-	async updateOne(data) {
-		return this._request("PATCH", "", data);
-	}
-	async bulkUpdate(data) {
+	/**
+	* `PATCH /` — partial update one or many records by primary key.
+	*/
+	async update(data) {
+		await this._validateData(data, "patch");
 		return this._request("PATCH", "", data);
 	}
-	async replaceOne(data) {
+	/**
+	* `PUT /` — full replace one or many records by primary key.
+	*/
+	async replace(data) {
+		await this._validateData(data, "replace");
 		return this._request("PUT", "", data);
 	}
-	async bulkReplace(data) {
-		return this._request("PUT", "", data);
-	}
-	async deleteOne(id) {
+	/**
+	* `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
+	*/
+	async remove(id) {
 		if (id !== null && typeof id === "object") return this._request("DELETE", `?${this._idToParams(id).toString()}`);
 		return this._request("DELETE", encodeURIComponent(String(id)));
 	}
+	/**
+	* `GET /meta` — table/view metadata (cached after first call).
+	*/
 	async meta() {
-		if (!this._metaPromise) this._metaPromise = this._request("GET", "meta");
+		if (!this._metaPromise) this._metaPromise = this._request("GET", "meta").catch((err) => {
+			this._metaPromise = void 0;
+			throw err;
+		});
 		return this._metaPromise;
 	}
+	/**
+	* Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
+	* Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
+	*/
+	getValidator() {
+		return this._getValidator();
+	}
+	async _validateData(data, mode) {
+		(await this._getValidator()).validate(data, mode);
+	}
+	_getValidator() {
+		if (!this._validatorPromise) this._validatorPromise = Promise.all([this.meta(), Promise.resolve().then(() => require("./validator.cjs"))]).then(([m, { createClientValidator }]) => createClientValidator(m)).catch((err) => {
+			this._validatorPromise = void 0;
+			throw err;
+		});
+		return this._validatorPromise;
+	}
 	_idToParams(id) {
 		const params = new URLSearchParams();
 		for (const [k, v] of Object.entries(id)) params.set(k, String(v));
 		return params;
 	}
+	async _getOrNull(endpoint) {
+		try {
+			return await this._request("GET", endpoint);
+		} catch (e) {
+			if (e instanceof ClientError && e.status === 404) return null;
+			throw e;
+		}
+	}
 	async _get(endpoint, query) {
 		const qs = query ? (0, _uniqu_url_builder.buildUrl)(query) : "";
 		return this._request("GET", `${endpoint}${qs ? `?${qs}` : ""}`);