@dynamicforms/fastapi-viewsets 0.3.6 → 0.5.0

package/README.md

@@ -8,12 +8,29 @@ Celery-backed async execution and a matching Vue/TypeScript client counterpart.
   Handles type resolution, lifecycle management and OpenAPI schema automatically.
 - **`CollectionViewSet`** — zero-boilerplate in-memory viewset backed by any Python list, set or dict.
   Great for prototyping and testing.
+- **`DjangoORMViewSet`** — back a viewset with a Django QuerySet. The filters it can compile, the
+  sort order with its NULL placement, the page as LIMIT/OFFSET and the total as `COUNT(*)` all
+  become SQL; a stage it declines falls back to the in-memory pass instead of failing, and
+  `pk_field_name` comes from the model's primary key (requires the `django` extra).
 - **`celery_viewset` decorator** — move a viewset's execution to a Celery worker with no code changes
   to the viewset itself, for long-running or background processing scenarios (requires the `celery`
   extra).
 - **Bulk operations** — first-class support for bulk create, update, partial update and destroy.
-- **Vue / TypeScript counterpart** — mirror mixin classes and a `route_rest` factory give you a fully
-  typed HTTP client that matches your backend viewset exactly (published separately as
+- **muxws transport** — reach the same viewsets over a single WebSocket instead of one HTTP request
+  per call. A command is dispatched into an app built from the endpoints published on muxws, each
+  carrying the route kwargs REST is given, so validation, dependencies, response models and the
+  command middleware from `settings.viewsets_command_middleware` behave identically; that app is the
+  library's own, so what you attached anywhere but the endpoint itself sees a command only if you
+  pass your app to `process_command`. In the demo, a burst of 100 requests takes 156 ms over REST
+  and 37 ms over muxws.
+- **Three list shapes** — a bare array, offset paging, or cursor paging. A viewset declares which,
+  and may let a client pick per request with an `X-List-Shape` header.
+- **Declarative filters** — declare which fields accept which operators and get query parameters,
+  an OpenAPI schema and filtering for free; backends translate what they can into their own query.
+- **Vue / TypeScript counterpart** — mirror mixin classes and the `restViewSet` / `muxwsViewSet` class
+  factory give you a fully typed client that matches your backend viewset exactly: the mixins a ViewSet
+  declares are its public surface, so calling an action it did not declare is a compile error rather
+  than a runtime 404 (published separately as
   [`@dynamicforms/fastapi-viewsets`](https://www.npmjs.com/package/@dynamicforms/fastapi-viewsets) on npm).
 
 ## Installation
@@ -23,6 +40,12 @@ pip install dynamicforms-fastapi-viewsets
 
 # with Celery-backed viewset support
 pip install "dynamicforms-fastapi-viewsets[celery]"
+
+# with the muxws WebSocket transport
+pip install "dynamicforms-fastapi-viewsets[muxws]"
+
+# with the Django ORM backend (Django 4.2+ and asgiref)
+pip install "dynamicforms-fastapi-viewsets[django]"
 ```
 
 Requires Python 3.10+, FastAPI and Pydantic v2.
@@ -59,7 +82,23 @@ app.include_router(router)
 ```
 
 See the [full documentation](https://docs.velis.si/dynamicforms/fastapi-viewsets/) for guides on
-the mixin system, `route_viewset`, `CollectionViewSet`, `celery_viewset`, and the Vue client.
+the mixin system, `route_viewset`, `CollectionViewSet`, `DjangoORMViewSet`, `celery_viewset`, the
+list pipeline and pagination, the muxws transport, and the Vue client.
+
+## Demo
+
+```bash
+python demo.py                       # backend on :8000, frontend on :5173
+python demo.py --celery              # ... with every viewset call routed through a Celery worker
+npm run test:e2e                     # drives the demo in a browser
+```
+
+An infinite-scrolling grid over a 5000-track library, cursor-paged. Switch the whole grid between
+the REST and muxws transports and between the in-memory and SQLite backends, and compare their
+latency side by side. Sorting and filtering are server-side.
+
+`--celery` needs Redis on localhost:6379. The end-to-end suite starts its own backend and dev
+server on their own ports.
 
 ## License
 

package/dist/fastapi-viewsets.js

@@ -1,5 +1,5 @@
 import e from "axios";
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/typeof.js
 function t(e) {
 	"@babel/helpers - typeof";
 	return t = typeof Symbol == "function" && typeof Symbol.iterator == "symbol" ? function(e) {
@@ -9,7 +9,7 @@ function t(e) {
 	}, t(e);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/toPrimitive.js
 function n(e, n) {
 	if (t(e) != "object" || !e) return e;
 	var r = e[Symbol.toPrimitive];
@@ -21,13 +21,13 @@ function n(e, n) {
 	return (n === "string" ? String : Number)(e);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/toPropertyKey.js
 function r(e) {
 	var r = n(e, "string");
 	return t(r) == "symbol" ? r : r + "";
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/defineProperty.js
 function i(e, t, n) {
 	return (t = r(t)) in e ? Object.defineProperty(e, t, {
 		value: n,
@@ -37,8 +37,54 @@ function i(e, t, n) {
 	}) : e[t] = n, e;
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.133.0/helpers/esm/asyncToGenerator.js
-function a(e, t, n, r, i, a, o) {
+//#region vue/mixins.ts
+var a = class {};
+i(a, "actions", ["create"]);
+var o = class {};
+i(o, "actions", ["bulkCreate"]);
+var s = class extends a {};
+i(s, "actions", [...a.actions, ...o.actions]);
+var c = class {};
+i(c, "actions", ["list"]);
+var l = class {};
+i(l, "actions", ["listCursor"]);
+var u = class {};
+i(u, "actions", ["listPage"]);
+var d = class {};
+i(d, "actions", ["retrieve"]);
+var f = class {};
+i(f, "actions", ["update", "partialUpdate"]);
+var p = class {};
+i(p, "actions", ["bulkUpdate", "bulkPartialUpdate"]);
+var m = class extends f {};
+i(m, "actions", [...f.actions, ...p.actions]);
+var h = class {};
+i(h, "actions", ["destroy"]);
+var g = class {};
+i(g, "actions", ["bulkDestroy"]);
+var _ = class extends h {};
+i(_, "actions", [...h.actions, ...g.actions]);
+var v = class {};
+i(v, "actions", ["lookup"]);
+var y = class extends c {};
+i(y, "actions", [...c.actions, ...d.actions]);
+var b = class extends y {};
+i(b, "actions", [
+	...y.actions,
+	...a.actions,
+	...f.actions,
+	...h.actions
+]);
+var x = class extends b {};
+i(x, "actions", [
+	...b.actions,
+	...o.actions,
+	...p.actions,
+	...g.actions
+]);
+//#endregion
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/asyncToGenerator.js
+function S(e, t, n, r, i, a, o) {
 	try {
 		var s = e[a](o), c = s.value;
 	} catch (e) {
@@ -47,24 +93,32 @@ function a(e, t, n, r, i, a, o) {
 	}
 	s.done ? t(c) : Promise.resolve(c).then(r, i);
 }
-function o(e) {
+function C(e) {
 	return function() {
 		var t = this, n = arguments;
 		return new Promise(function(r, i) {
-			var o = e.apply(t, n);
-			function s(e) {
-				a(o, r, i, s, c, "next", e);
+			var a = e.apply(t, n);
+			function o(e) {
+				S(a, r, i, o, s, "next", e);
 			}
-			function c(e) {
-				a(o, r, i, s, c, "throw", e);
+			function s(e) {
+				S(a, r, i, o, s, "throw", e);
 			}
-			s(void 0);
+			o(void 0);
 		});
 	};
 }
 //#endregion
-//#region vue/rest-proxy.ts
-var s = new Set([
+//#region vue/proxy-base.ts
+var w = class extends Error {
+	constructor(e, t, n = {}) {
+		super(`Request failed with status code ${e}`), i(this, "response", void 0), this.name = "ViewSetRequestError", this.response = {
+			status: e,
+			data: t,
+			headers: n
+		};
+	}
+}, T = /* @__PURE__ */ new Set([
 	"get",
 	"post",
 	"put",
@@ -73,26 +127,32 @@ var s = new Set([
 	"head",
 	"options",
 	"trace"
-]), c = {
+]), E = {
 	base: {
-		GET: "list",
-		POST: "create"
+		GET: [
+			"list",
+			"listPage",
+			"listCursor"
+		],
+		POST: ["create"]
 	},
 	pk: {
-		GET: "retrieve",
-		PUT: "update",
-		PATCH: "partialUpdate",
-		DELETE: "destroy"
+		GET: ["retrieve"],
+		PUT: ["update"],
+		PATCH: ["partialUpdate"],
+		DELETE: ["destroy"]
 	},
 	bulk: {
-		POST: "bulkCreate",
-		PUT: "bulkUpdate",
-		PATCH: "bulkPartialUpdate",
-		DELETE: "bulkDestroy"
+		POST: ["bulkCreate"],
+		PUT: ["bulkUpdate"],
+		PATCH: ["bulkPartialUpdate"],
+		DELETE: ["bulkDestroy"]
 	},
-	lookup: { GET: "lookup" }
-}, l = [
+	lookup: { GET: ["lookup"] }
+}, D = [
 	"list",
+	"listPage",
+	"listCursor",
 	"create",
 	"retrieve",
 	"update",
@@ -103,119 +163,299 @@ var s = new Set([
 	"bulkPartialUpdate",
 	"bulkDestroy",
 	"lookup"
-], u = class {
-	constructor(t) {
-		var n;
-		i(this, "http", void 0), i(this, "basePath", void 0), i(this, "pkFieldName", void 0), this.basePath = t.basePath.replace(/\/$/, ""), this.pkFieldName = t.pkFieldName, this.http = (n = t.axiosInstance) == null ? e : n, this.validateAgainstSchema();
+];
+function O(e, t) {
+	var n;
+	let r = t == null ? e.constructor.declares : t;
+	if (!Array.isArray(r)) return null;
+	let i = /* @__PURE__ */ new Set();
+	for (let e of r) for (let t of (n = e == null ? void 0 : e.actions) == null ? [] : n) i.add(t);
+	return i;
+}
+var k = class {
+	constructor(e) {
+		i(this, "basePath", void 0), this.basePath = e.replace(/\/$/, "");
+	}
+	request(e, t, n) {
+		throw Error("ViewSetInternals.request: no transport");
+	}
+}, A = class extends k {
+	constructor(e) {
+		super(e.basePath), i(this, "pkFieldName", void 0), i(this, "schemaValidationEnabled", void 0), i(this, "declaredMixins", void 0), this.pkFieldName = e.pkFieldName, this.schemaValidationEnabled = e.validateSchema !== !1, this.declaredMixins = e.declares;
+	}
+	initSchemaValidation() {
+		this.schemaValidationEnabled && this.validateAgainstSchema();
 	}
 	validateAgainstSchema() {
 		var e = this;
-		return o(function* () {
-			try {
-				var t, n;
-				let i = (t = (n = (yield e.http.get(`${e.basePath}/schema`)).data) == null ? void 0 : n.paths) == null ? {} : t, a = /* @__PURE__ */ new Set(), o = [];
-				for (let [t, n] of Object.entries(i)) {
+		return C(function* () {
+			let t = O(e, e.declaredMixins);
+			if (t !== null) try {
+				var n;
+				let i = yield e.request("GET", "/schema"), a = (n = i == null ? void 0 : i.paths) == null ? {} : n, o = /* @__PURE__ */ new Set(), s = [], c = [];
+				for (let [t, n] of Object.entries(a)) {
 					var r;
-					let i = t.slice(e.basePath.length).replace(/^\//, ""), l;
+					let i = t.slice(e.basePath.length).replace(/^\//, ""), a = Object.keys(n).filter((e) => T.has(e.toLowerCase())), l;
 					if (i === "") l = "base";
 					else if (i === "bulk") l = "bulk";
 					else if (i === "lookup") l = "lookup";
 					else if (i === "schema") continue;
-					else if (i.startsWith("{")) l = "pk";
+					else if (i.startsWith("{") && !i.includes("/")) l = "pk";
 					else {
-						for (let e of Object.keys(n)) s.has(e.toLowerCase()) && o.push(`${e.toUpperCase()} ${t}`);
+						for (let e of a) c.push({
+							endpoint: `${e.toUpperCase()} ${t}`,
+							method: i.split("/")[0]
+						});
 						continue;
 					}
-					let u = (r = c[l]) == null ? {} : r;
-					for (let e of Object.keys(n)) {
-						if (!s.has(e.toLowerCase())) continue;
-						let t = u[e.toUpperCase()];
-						t && a.add(t);
+					let u = (r = E[l]) == null ? {} : r;
+					for (let e of a) {
+						let n = u[e.toUpperCase()];
+						if (n) {
+							s.push({
+								endpoint: `${e.toUpperCase()} ${t}`,
+								actions: n
+							});
+							for (let e of n) o.add(e);
+						}
 					}
 				}
-				let u = [];
-				for (let t of l) typeof e[t] == "function" && !a.has(t) && u.push(`FE declares '${t}()' but BE has no matching endpoint`);
-				for (let t of a) typeof e[t] != "function" && u.push(`BE exposes '${t}' endpoint but FE does not implement it`);
-				for (let e of o) u.push(`BE has non-standard endpoint '${e}' with no FE method`);
-				u.length > 0 && console.warn(`[ViewSet ${e.basePath}] FE/BE definition mismatch:\n` + u.map((e) => `  • ${e}`).join("\n"));
+				let l = [];
+				for (let e of D) t.has(e) && !o.has(e) && l.push(`declares '${e}' but the BE viewset serves no such endpoint`);
+				for (let { endpoint: e, actions: n } of s) n.some((e) => t.has(e)) || l.push(`BE serves '${e}' but the ViewSet declares no ${n.join(" / ")}`);
+				for (let { endpoint: t, method: n } of c) typeof e[n] != "function" && l.push(`BE serves '${t}' but the ViewSet has no '${n}()' method`);
+				l.length > 0 && console.warn(`[ViewSet ${e.basePath}] FE/BE definition mismatch:\n` + l.map((e) => `  • ${e}`).join("\n"));
 			} catch (e) {}
 		})();
 	}
 	create(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.post(t.basePath, e)).data;
+		return C(function* () {
+			return t.request("POST", "", { body: e });
 		})();
 	}
 	bulkCreate(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.post(`${t.basePath}/bulk`, e)).data;
+		return C(function* () {
+			return t.request("POST", "/bulk", { body: e });
 		})();
 	}
-	list() {
-		var e = this;
-		return o(function* () {
-			return (yield e.http.get(e.basePath)).data;
+	list(e) {
+		var t = this;
+		return C(function* () {
+			return t.request("GET", "", { query: e });
+		})();
+	}
+	listCursor(e) {
+		var t = this;
+		return C(function* () {
+			let n = yield t.request("GET", "", { query: e });
+			return {
+				results: n.results,
+				limit: n.limit,
+				hasMore: n.has_more,
+				hasPrevious: n.has_previous,
+				next: n.next,
+				previous: n.previous,
+				first: n.first,
+				last: n.last
+			};
+		})();
+	}
+	listPage(e) {
+		var t = this;
+		return C(function* () {
+			let n = yield t.request("GET", "", { query: e });
+			return {
+				results: n.results,
+				offset: n.offset,
+				limit: n.limit,
+				count: n.count,
+				hasMore: n.has_more,
+				hasPrevious: n.has_previous
+			};
 		})();
 	}
 	retrieve(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.get(`${t.basePath}/${e}`)).data;
+		return C(function* () {
+			return t.request("GET", `/${e}`);
 		})();
 	}
 	update(e, t) {
 		var n = this;
-		return o(function* () {
-			return (yield n.http.put(`${n.basePath}/${e}`, t)).data;
+		return C(function* () {
+			return n.request("PUT", `/${e}`, { body: t });
 		})();
 	}
 	partialUpdate(e, t) {
 		var n = this;
-		return o(function* () {
-			return (yield n.http.patch(`${n.basePath}/${e}`, t)).data;
+		return C(function* () {
+			return n.request("PATCH", `/${e}`, { body: t });
 		})();
 	}
 	bulkUpdate(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.put(`${t.basePath}/bulk`, e)).data;
+		return C(function* () {
+			return t.request("PUT", "/bulk", { body: e });
 		})();
 	}
 	bulkPartialUpdate(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.patch(`${t.basePath}/bulk`, e)).data;
+		return C(function* () {
+			return t.request("PATCH", "/bulk", { body: e });
 		})();
 	}
 	destroy(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.delete(`${t.basePath}/${e}`)).data;
+		return C(function* () {
+			return t.request("DELETE", `/${e}`);
 		})();
 	}
 	bulkDestroy(e) {
 		var t = this;
-		return o(function* () {
-			return (yield t.http.delete(`${t.basePath}/bulk`, { data: e })).data;
+		return C(function* () {
+			return t.request("DELETE", "/bulk", { body: e });
 		})();
 	}
 	lookup() {
 		var e = this;
-		return o(function* () {
-			return (yield e.http.get(`${e.basePath}/lookup`)).data;
+		return C(function* () {
+			return e.request("GET", "/lookup");
 		})();
 	}
 };
-function d(e, t, n, r) {
-	return new u(typeof t == "string" ? {
+i(A, "declares", void 0);
+//#endregion
+//#region \0@oxc-project+runtime@0.146.0/helpers/esm/objectSpread2.js
+function j(e, t) {
+	var n = Object.keys(e);
+	if (Object.getOwnPropertySymbols) {
+		var r = Object.getOwnPropertySymbols(e);
+		t && (r = r.filter(function(t) {
+			return Object.getOwnPropertyDescriptor(e, t).enumerable;
+		})), n.push.apply(n, r);
+	}
+	return n;
+}
+function M(e) {
+	for (var t = 1; t < arguments.length; t++) {
+		var n = arguments[t] == null ? {} : arguments[t];
+		t % 2 ? j(Object(n), !0).forEach(function(t) {
+			i(e, t, n[t]);
+		}) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(n)) : j(Object(n)).forEach(function(t) {
+			Object.defineProperty(e, t, Object.getOwnPropertyDescriptor(n, t));
+		});
+	}
+	return e;
+}
+//#endregion
+//#region vue/muxws-proxy.ts
+var N = class extends A {
+	constructor(e) {
+		var t;
+		super(e), i(this, "peerSource", void 0), i(this, "timeoutMs", void 0), i(this, "headers", void 0), i(this, "peerPromise", void 0), this.peerSource = e.peer, this.timeoutMs = e.timeoutMs, this.headers = (t = e.headers) == null ? {} : t, this.initSchemaValidation();
+	}
+	peer() {
+		if (!this.peerPromise) {
+			let e = this.peerSource;
+			this.peerPromise = Promise.resolve(typeof e == "function" ? e() : e);
+		}
+		return this.peerPromise;
+	}
+	request(e, t) {
+		var n = this;
+		return C(function* (e, t, r = {}) {
+			let i = yield n.peer(), a = M(M({}, n.headers), {}, {
+				":method": e,
+				":path": `${n.basePath}${t}`
+			});
+			r.query && Object.keys(r.query).length > 0 && (a[":query"] = P(r.query));
+			let o = i.open(r.body, {
+				headers: a,
+				end: !0
+			});
+			yield o.replyHeadersArrived;
+			let s = F(o.replyHeaders), c = yield o.result(n.timeoutMs === void 0 ? void 0 : { timeoutMs: n.timeoutMs });
+			if (s >= 400) throw new w(s, c, I(o.replyHeaders));
+			return c;
+		}).apply(this, arguments);
+	}
+};
+function P(e) {
+	let t = {};
+	for (let [n, r] of Object.entries(e)) r != null && (t[n] = r);
+	return t;
+}
+function F(e) {
+	let t = e == null ? void 0 : e[":status"];
+	if (typeof t == "number") return t;
+	if (typeof t == "string") {
+		let e = Number.parseInt(t, 10);
+		if (!Number.isNaN(e)) return e;
+	}
+	return 200;
+}
+function I(e) {
+	let t = {};
+	for (let [n, r] of Object.entries(e == null ? {} : e)) n.startsWith(":") || (t[n] = String(r));
+	return t;
+}
+function L(e, t) {
+	return new N(M({ declares: e.declares }, t));
+}
+//#endregion
+//#region vue/rest-proxy.ts
+var R = class extends A {
+	constructor(t) {
+		var n;
+		super(t), i(this, "http", void 0), this.http = (n = t.axiosInstance) == null ? e : n, this.initSchemaValidation();
+	}
+	request(e, t) {
+		var n = this;
+		return C(function* (e, t, r = {}) {
+			let i = `${n.basePath}${t}`, a = r.query !== void 0 && Object.keys(r.query).length > 0 ? { params: r.query } : void 0;
+			switch (e) {
+				case "GET": return (a ? yield n.http.get(i, a) : yield n.http.get(i)).data;
+				case "POST": return (a ? yield n.http.post(i, r.body, a) : yield n.http.post(i, r.body)).data;
+				case "PUT": return (a ? yield n.http.put(i, r.body, a) : yield n.http.put(i, r.body)).data;
+				case "PATCH": return (a ? yield n.http.patch(i, r.body, a) : yield n.http.patch(i, r.body)).data;
+				case "DELETE": {
+					let e = r.body === void 0 ? a : M(M({}, a == null ? {} : a), {}, { data: r.body });
+					return (e ? yield n.http.delete(i, e) : yield n.http.delete(i)).data;
+				}
+			}
+		}).apply(this, arguments);
+	}
+};
+function z(e, t, n, r) {
+	let i = typeof t == "string" ? {
 		basePath: t,
 		pkFieldName: n,
 		axiosInstance: r
-	} : t);
+	} : t;
+	return new R(M({ declares: e.declares }, i));
+}
+//#endregion
+//#region vue/viewset.ts
+function B(e, t, n) {
+	var r;
+	return r = class extends e {
+		constructor(e) {
+			super(M(M({}, e), {}, {
+				pkFieldName: t,
+				declares: void 0
+			}));
+		}
+	}, i(r, "declares", n), r;
+}
+function V() {
+	return (e, t) => B(R, e, t);
+}
+function H() {
+	return (e, t) => B(N, e, t);
 }
 //#endregion
-export { u as RestProxyImpl, d as route_rest };
+export { s as BulkCreateMixin, _ as BulkDestroyMixin, o as BulkOnlyCreateMixin, g as BulkOnlyDestroyMixin, p as BulkOnlyUpdateMixin, m as BulkUpdateMixin, x as BulkViewSetMixin, a as CreateMixin, l as CursorListMixin, h as DestroyMixin, c as ListMixin, v as LookupMixin, N as MuxwsProxyImpl, u as PaginatedListMixin, y as ReadOnlyViewSetMixin, R as RestProxyImpl, d as RetrieveMixin, f as UpdateMixin, k as ViewSetInternals, b as ViewSetMixin, A as ViewSetProxyBase, w as ViewSetRequestError, H as muxwsViewSet, V as restViewSet, L as route_muxws, z as route_rest };
 
 //# sourceMappingURL=fastapi-viewsets.js.map