@danceroutine/tango-resources 0.1.0 → 1.0.0

package/dist/index.js

@@ -1,42 +1,51 @@
-import { z } from "zod";
-import { toHttpError } from "@danceroutine/tango-core";
+import { APIView, CreateAPIView, CreateModelMixin, DestroyModelMixin, GenericAPIView, ListAPIView, ListCreateAPIView, ListModelMixin, OffsetPaginationInput, OffsetPaginator, RetrieveAPIView, RetrieveDestroyAPIView, RetrieveModelMixin, RetrieveUpdateAPIView, RetrieveUpdateDestroyAPIView, UpdateModelMixin, __export, view_exports } from "./view-BNGEURL_.js";
+import { HttpErrorFactory, NotFoundError, TangoRequest, TangoResponse } from "@danceroutine/tango-core";
+import { z, z as z$1 } from "zod";
 import { Q } from "@danceroutine/tango-orm";
 
-//#region rolldown:runtime
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-};
-
-//#endregion
 //#region src/context/RequestContext.ts
 var RequestContext = class RequestContext {
 	static BRAND = "tango.resources.request_context";
-	state = new Map();
 	__tangoBrand = RequestContext.BRAND;
+	state = new Map();
 	constructor(request, user = null, params = {}) {
 		this.request = request;
 		this.user = user;
 		this.params = params;
 	}
+	/**
+	* Narrow an unknown value to `RequestContext`.
+	*/
 	static isRequestContext(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === RequestContext.BRAND;
 	}
+	/**
+	* Construct a context with optional user payload.
+	*/
+	static create(request, user) {
+		return new RequestContext(TangoRequest.isTangoRequest(request) ? request : new TangoRequest(request), user ?? null);
+	}
+	/**
+	* Store arbitrary per-request state for downstream middleware/handlers.
+	*/
 	setState(key, value) {
 		this.state.set(key, value);
 	}
+	/**
+	* Retrieve previously stored request state.
+	*/
 	getState(key) {
 		return this.state.get(key);
 	}
+	/**
+	* Check whether a state key has been set.
+	*/
 	hasState(key) {
 		return this.state.has(key);
 	}
-	static create(request, user) {
-		return new RequestContext(request, user ?? null);
-	}
+	/**
+	* Clone the context, including route params and request-local state.
+	*/
 	clone() {
 		const cloned = new RequestContext(this.request, this.user, { ...this.params });
 		cloned.state = new Map(this.state);
@@ -64,29 +73,200 @@ const InternalFilterType = {
 var FilterSet = class FilterSet {
 	static BRAND = "tango.resources.filter_set";
 	__tangoBrand = FilterSet.BRAND;
+	/**
+	* Resolve matching query parameters into ORM filter inputs.
+	*/
+	constructor(spec, allowAllParams = false) {
+		this.spec = spec;
+		this.allowAllParams = allowAllParams;
+	}
+	/**
+	* Build a filter set from Django-style field declarations.
+	*/
+	static define(config) {
+		const spec = FilterSet.normalizeDefineConfig(config);
+		return new FilterSet(spec, config.all === "__all__");
+	}
+	/**
+	* Narrow an unknown value to `FilterSet`.
+	*/
 	static isFilterSet(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === FilterSet.BRAND;
 	}
-	constructor(spec) {
-		this.spec = spec;
+	static normalizeDefineConfig(config) {
+		const spec = {};
+		const fieldDeclarations = config.fields ?? {};
+		const fieldParsers = config.parsers ?? {};
+		for (const rawField of Object.keys(fieldDeclarations)) {
+			const declaration = fieldDeclarations[rawField];
+			if (declaration === undefined) continue;
+			const parser = fieldParsers[rawField];
+			FilterSet.addFieldDeclaration(spec, rawField, declaration, parser);
+		}
+		const aliases = config.aliases ?? {};
+		for (const [param, declaration] of Object.entries(aliases)) spec[param] = FilterSet.normalizeAliasDeclaration(declaration);
+		return spec;
+	}
+	static addFieldDeclaration(spec, field, declaration, parser) {
+		if (declaration === true) {
+			spec[String(field)] = FilterSet.createLookupResolver(field, "exact", parser);
+			return;
+		}
+		if (FilterSet.isLookupArray(declaration)) {
+			for (const lookup of declaration) {
+				const param = FilterSet.resolveLookupParam(String(field), lookup);
+				spec[param] = FilterSet.createLookupResolver(field, lookup, parser);
+			}
+			return;
+		}
+		const lookups = declaration.lookups ?? ["exact"];
+		const baseParam = declaration.param ?? String(field);
+		const effectiveParser = declaration.parse ?? parser;
+		for (const lookup of lookups) {
+			const param = FilterSet.resolveLookupParam(baseParam, lookup);
+			spec[param] = FilterSet.createLookupResolver(field, lookup, effectiveParser);
+		}
 	}
+	static isLookupArray(value) {
+		return Array.isArray(value);
+	}
+	static normalizeAliasDeclaration(declaration) {
+		if (FilterSet.isFilterResolverDeclaration(declaration)) return declaration;
+		if ("fields" in declaration) {
+			const lookup = declaration.lookup ?? "icontains";
+			return FilterSet.createMultiFieldResolver(declaration.fields, lookup, declaration.parse);
+		}
+		return FilterSet.createLookupResolver(declaration.field, declaration.lookup ?? "exact", declaration.parse);
+	}
+	static isFilterResolverDeclaration(value) {
+		if (typeof value !== "object" || value === null || !("type" in value)) return false;
+		return [
+			InternalFilterType.SCALAR,
+			InternalFilterType.ILIKE,
+			InternalFilterType.RANGE,
+			InternalFilterType.IN,
+			InternalFilterType.CUSTOM
+		].includes(value.type);
+	}
+	static createMultiFieldResolver(fields, lookup, parser) {
+		if (lookup === "icontains" && parser === undefined) return {
+			type: InternalFilterType.ILIKE,
+			columns: [...fields]
+		};
+		return {
+			type: InternalFilterType.CUSTOM,
+			apply: (raw) => {
+				const parsed = FilterSet.resolveParserValue(raw, parser);
+				if (parsed === undefined) return undefined;
+				const composed = {};
+				for (const field of fields) {
+					const segment = FilterSet.resolveLookupFilter(field, lookup, parsed);
+					if (!segment) continue;
+					Object.assign(composed, segment);
+				}
+				return Object.keys(composed).length > 0 ? composed : undefined;
+			}
+		};
+	}
+	static createLookupResolver(field, lookup, parser) {
+		if (parser !== undefined) return {
+			type: InternalFilterType.CUSTOM,
+			apply: (raw) => {
+				const parsed = FilterSet.resolveParserValue(raw, parser);
+				if (parsed === undefined) return undefined;
+				return FilterSet.resolveLookupFilter(field, lookup, parsed);
+			}
+		};
+		switch (lookup) {
+			case "exact": return {
+				type: InternalFilterType.SCALAR,
+				column: field
+			};
+			case "in": return {
+				type: InternalFilterType.IN,
+				column: field
+			};
+			case "lt":
+			case "lte":
+			case "gt":
+			case "gte": return {
+				type: InternalFilterType.RANGE,
+				column: field,
+				op: lookup
+			};
+			case "icontains": return {
+				type: InternalFilterType.ILIKE,
+				columns: [field]
+			};
+			default: return {
+				type: InternalFilterType.CUSTOM,
+				apply: (raw) => FilterSet.resolveLookupFilter(field, lookup, raw)
+			};
+		}
+	}
+	static resolveLookupFilter(field, lookup, value) {
+		if (value === undefined) return undefined;
+		if (lookup === "exact") return { [field]: value };
+		if (lookup === "in") {
+			const arr = Array.isArray(value) ? value : String(value).split(",");
+			const lookupKey$1 = `${String(field)}__in`;
+			return { [lookupKey$1]: arr };
+		}
+		if (lookup === "icontains") {
+			const lookupKey$1 = `${String(field)}__icontains`;
+			return { [lookupKey$1]: `%${FilterSet.toScalarString(value)}%` };
+		}
+		const lookupKey = `${String(field)}__${lookup}`;
+		return { [lookupKey]: value };
+	}
+	static resolveLookupParam(baseParam, lookup) {
+		if (lookup === "exact") return baseParam;
+		return `${baseParam}__${lookup}`;
+	}
+	static resolveParserValue(value, parser) {
+		if (value === undefined) return undefined;
+		if (parser === undefined) return value;
+		return parser(value);
+	}
+	static toScalarString(value) {
+		if (Array.isArray(value)) return value.join(",");
+		return String(value);
+	}
+	/**
+	* Apply all configured resolvers against query params.
+	*/
 	apply(params) {
 		const filters = [];
-		for (const [key, resolver] of Object.entries(this.spec)) {
+		const keys = new Set();
+		for (const [key] of params.entries()) keys.add(key);
+		for (const key of keys) {
+			const resolver = this.spec[key] ?? (this.allowAllParams ? this.buildAllResolver(key) : undefined);
+			if (!resolver) continue;
 			const rawValue = params.getAll(key);
-			const value = rawValue.length > 1 ? rawValue : params.get(key) ?? undefined;
+			const value = rawValue.length > 1 ? rawValue : rawValue[0];
 			if (value === undefined) continue;
 			const filter = this.resolveFilter(resolver, value);
 			if (filter) filters.push(filter);
 		}
 		return filters;
 	}
+	buildAllResolver(param) {
+		const [rawField, ...rawLookupParts] = param.split("__");
+		if (!rawField) return undefined;
+		const field = rawField;
+		if (rawLookupParts.length === 0) return {
+			type: InternalFilterType.SCALAR,
+			column: field
+		};
+		const lookup = rawLookupParts.join("__");
+		return FilterSet.createLookupResolver(field, lookup);
+	}
 	resolveFilter(resolver, value) {
 		if (value === undefined) return undefined;
 		switch (resolver.type) {
 			case InternalFilterType.SCALAR: return { [resolver.column]: value };
 			case InternalFilterType.ILIKE: {
-				const pattern = `%${value}%`;
+				const pattern = `%${FilterSet.toScalarString(value)}%`;
 				const filter = {};
 				resolver.columns.forEach((col) => {
 					filter[`${String(col)}__icontains`] = pattern;
@@ -114,136 +294,36 @@ var filters_exports = {};
 __export(filters_exports, { FilterSet: () => FilterSet });
 
 //#endregion
-//#region src/pagination/PaginationInput.ts
-const PaginationInput = z.object({
-	limit: z.coerce.number().int().min(1).default(25).transform((value) => Math.min(value, 100)),
-	offset: z.coerce.number().int().min(0).default(0),
-	page: z.coerce.number().int().min(1).optional()
+//#region src/pagination/CursorPaginationInput.ts
+const CursorPaginationInput = z$1.object({
+	limit: z$1.preprocess((value) => {
+		if (value === undefined || value === null || value === "") return undefined;
+		const parsed = Number.parseInt(String(value), 10);
+		if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+		return parsed;
+	}, z$1.number().int().min(1).transform((value) => Math.min(value, 100)).optional()),
+	cursor: z$1.string().nullable().default(null),
+	ordering: z$1.string().optional()
 });
 
-//#endregion
-//#region src/paginators/OffsetPaginator.ts
-var OffsetPage = class OffsetPage {
-	static BRAND = "tango.resources.offset_page";
-	__tangoBrand = OffsetPage.BRAND;
-	static isOffsetPage(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === OffsetPage.BRAND;
-	}
-	constructor(results, pageNumber, perPage, totalCount) {
-		this.results = results;
-		this.pageNumber = pageNumber;
-		this.perPage = perPage;
-		this.totalCount = totalCount;
-	}
-	hasNext() {
-		if (this.totalCount === undefined) return false;
-		return this.endIndex() < this.totalCount;
-	}
-	hasPrevious() {
-		return this.pageNumber > 1;
-	}
-	nextPageNumber() {
-		return this.hasNext() ? this.pageNumber + 1 : null;
-	}
-	previousPageNumber() {
-		return this.hasPrevious() ? this.pageNumber - 1 : null;
-	}
-	startIndex() {
-		return (this.pageNumber - 1) * this.perPage;
-	}
-	endIndex() {
-		return this.startIndex() + this.results.length;
-	}
-};
-var OffsetPaginator = class OffsetPaginator {
-	static BRAND = "tango.resources.offset_paginator";
-	__tangoBrand = OffsetPaginator.BRAND;
-	limit = 25;
-	offset = 0;
-	constructor(queryset, perPage = 25) {
-		this.queryset = queryset;
-		this.perPage = perPage;
-		this.limit = perPage;
-	}
-	static isOffsetPaginator(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === OffsetPaginator.BRAND;
-	}
-	/**
-	* Parse limit, offset, and page from URL search params.
-	* If `page` is provided, it's converted to an offset.
-	* Stores parsed values for use by getPaginatedResponse.
-	*/
-	parse(params) {
-		const input = {
-			limit: params.get("limit") ?? undefined,
-			offset: params.get("offset") ?? undefined,
-			page: params.get("page") ?? undefined
-		};
-		const parsed = PaginationInput.parse(input);
-		if (parsed.page) parsed.offset = (parsed.page - 1) * parsed.limit;
-		this.limit = parsed.limit;
-		this.offset = parsed.offset;
-	}
-	parseParams(params) {
-		this.parse(params);
-		return {
-			limit: this.limit,
-			offset: this.offset
-		};
-	}
-	/**
-	* Build a DRF-style paginated response with count, next, and previous links.
-	* Uses the limit/offset stored from the most recent parseParams call.
-	*/
-	toResponse(results, context) {
-		const totalCount = context?.totalCount;
-		const response = { results };
-		if (totalCount !== undefined) {
-			response.count = totalCount;
-			if (this.offset + this.limit < totalCount) response.next = `?limit=${this.limit}&offset=${this.offset + this.limit}`;
-			if (this.offset > 0) {
-				const prevOffset = Math.max(0, this.offset - this.limit);
-				response.previous = `?limit=${this.limit}&offset=${prevOffset}`;
-			}
-		}
-		return response;
-	}
-	getPaginatedResponse(results, totalCount) {
-		return this.toResponse(results, { totalCount });
-	}
-	apply(queryset) {
-		return queryset.limit(this.limit).offset(this.offset);
-	}
-	async paginate(page) {
-		return this.getPage(page);
-	}
-	async getPage(page) {
-		const offset = (page - 1) * this.perPage;
-		const results = await this.queryset.offset(offset).limit(this.perPage).fetch();
-		const totalCount = await this.count();
-		return new OffsetPage(results.results, page, this.perPage, totalCount);
-	}
-	async count() {
-		return this.queryset.count();
-	}
-};
-
 //#endregion
 //#region src/paginators/CursorPaginator.ts
 var CursorPage = class CursorPage {
 	static BRAND = "tango.resources.cursor_page";
 	__tangoBrand = CursorPage.BRAND;
-	static isCursorPage(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === CursorPage.BRAND;
-	}
 	constructor(results, nextCursor, previousCursor) {
 		this.results = results;
 		this.nextCursor = nextCursor;
 		this.previousCursor = previousCursor;
 	}
+	static isCursorPage(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === CursorPage.BRAND;
+	}
+	/** Whether a next cursor token exists. */
 	hasNext() {
 		return this.nextCursor !== null;
 	}
+	/** Whether a previous cursor token exists. */
 	hasPrevious() {
 		return this.previousCursor !== null;
 	}
@@ -274,21 +354,33 @@ var CursorPaginator = class CursorPaginator {
 		this.cursorField = cursorField;
 		this.limit = perPage;
 	}
+	/**
+	* Narrow an unknown value to `CursorPaginator`.
+	*/
 	static isCursorPaginator(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === CursorPaginator.BRAND;
 	}
+	/**
+	* Parse cursor pagination parameters from Tango query params.
+	*/
 	parse(params) {
-		const rawLimit = Number.parseInt(params.get("limit") ?? "", 10);
-		if (Number.isFinite(rawLimit) && rawLimit > 0) this.limit = Math.min(rawLimit, 100);
-else this.limit = this.perPage;
-		this.cursor = params.get("cursor");
-		const ordering = params.get("ordering");
+		const parsed = CursorPaginationInput.parse({
+			limit: params.get("limit") ?? undefined,
+			cursor: params.get("cursor"),
+			ordering: params.get("ordering") ?? undefined
+		});
+		this.limit = parsed.limit ?? this.perPage;
+		this.cursor = parsed.cursor;
+		const ordering = parsed.ordering;
 		if (ordering) {
 			const parsedDirection = ordering.startsWith("-") ? "desc" : "asc";
 			const parsedField = ordering.startsWith("-") ? ordering.slice(1) : ordering;
 			this.direction = parsedField === String(this.cursorField) ? parsedDirection : "asc";
 		} else this.direction = "asc";
 	}
+	/**
+	* Parse params and return compatibility `{ limit, offset }` shape.
+	*/
 	parseParams(params) {
 		this.parse(params);
 		return {
@@ -296,15 +388,27 @@ else this.limit = this.perPage;
 			offset: 0
 		};
 	}
+	/**
+	* Build a paginated response payload with cursor links.
+	*/
+	needsTotalCount() {
+		return false;
+	}
 	toResponse(results) {
 		const response = { results };
 		if (this.nextCursor) response.next = this.buildPageLink(this.nextCursor);
 		if (this.previousCursor) response.previous = this.buildPageLink(this.previousCursor);
 		return response;
 	}
+	/**
+	* Backward-compatible alias for `toResponse`.
+	*/
 	getPaginatedResponse(results, _totalCount) {
 		return this.toResponse(results);
 	}
+	/**
+	* Apply cursor constraints and ordering to a queryset.
+	*/
 	apply(queryset) {
 		let qs = queryset.limit(this.limit + 1);
 		if (this.cursor) {
@@ -318,6 +422,9 @@ else this.limit = this.perPage;
 		const orderToken = this.direction === "asc" ? String(this.cursorField) : `-${String(this.cursorField)}`;
 		return qs.orderBy(orderToken);
 	}
+	/**
+	* Fetch the next cursor page.
+	*/
 	async paginate(cursor) {
 		const appliedCursor = cursor ?? this.cursor;
 		this.cursor = appliedCursor;
@@ -330,6 +437,9 @@ else this.limit = this.perPage;
 		this.nextCursor = hasMore && last ? this.encodeCursor(last) : null;
 		return new CursorPage(results, this.nextCursor, this.previousCursor);
 	}
+	/**
+	* Cursor paginators only support page `1` as an entry point.
+	*/
 	async getPage(page) {
 		if (page !== 1) throw new Error("CursorPaginator only supports getPage(1). Use cursor pagination for subsequent pages.");
 		return this.paginate();
@@ -363,9 +473,10 @@ else this.limit = this.perPage;
 //#region src/pagination/index.ts
 var pagination_exports = {};
 __export(pagination_exports, {
+	CursorPaginationInput: () => CursorPaginationInput,
 	CursorPaginator: () => CursorPaginator,
-	OffsetPaginator: () => OffsetPaginator,
-	PaginationInput: () => PaginationInput
+	OffsetPaginationInput: () => OffsetPaginationInput,
+	OffsetPaginator: () => OffsetPaginator
 });
 
 //#endregion
@@ -376,41 +487,229 @@ __export(paginators_exports, {
 	OffsetPaginator: () => OffsetPaginator
 });
 
+//#endregion
+//#region src/resource/index.ts
+var resource_exports = {};
+
+//#endregion
+//#region src/serializer/Serializer.ts
+var Serializer = class {
+	static createSchema = z.unknown();
+	static updateSchema = z.unknown();
+	static outputSchema = z.unknown();
+	/**
+	* Return the serializer class for the current instance.
+	*/
+	getSerializerClass() {
+		return this.constructor;
+	}
+	/**
+	* Return the Zod schema used for create payloads.
+	*/
+	getCreateSchema() {
+		return this.getSerializerClass().createSchema;
+	}
+	/**
+	* Return the Zod schema used for update payloads.
+	*/
+	getUpdateSchema() {
+		return this.getSerializerClass().updateSchema;
+	}
+	/**
+	* Return the Zod schema used for serialized output.
+	*/
+	getOutputSchema() {
+		return this.getSerializerClass().outputSchema;
+	}
+	/**
+	* Validate unknown input for create workflows.
+	*/
+	deserializeCreate(input) {
+		return this.getCreateSchema().parse(input);
+	}
+	/**
+	* Validate unknown input for update workflows.
+	*/
+	deserializeUpdate(input) {
+		return this.getUpdateSchema().parse(input);
+	}
+	/**
+	* Convert a persisted record into its outward-facing representation.
+	*/
+	toRepresentation(record) {
+		return this.getOutputSchema().parse(record);
+	}
+};
+
+//#endregion
+//#region src/serializer/ModelSerializer.ts
+var ModelSerializer = class extends Serializer {
+	static model;
+	/**
+	* Return the Tango model backing this serializer.
+	*/
+	getModel() {
+		const model = this.constructor.model;
+		if (!model) throw new Error(`${this.constructor.name} must define a static model or override getModel().`);
+		return model;
+	}
+	/**
+	* Return the manager used for create and update workflows.
+	*/
+	getManager() {
+		return this.getModel().objects;
+	}
+	/**
+	* Validate, enrich, persist, and serialize a create workflow.
+	*/
+	async create(input) {
+		const validated = this.deserializeCreate(input);
+		const prepared = await this.beforeCreate(validated);
+		const created = await this.getManager().create(prepared);
+		return this.toRepresentation(created);
+	}
+	/**
+	* Validate, enrich, persist, and serialize an update workflow.
+	*/
+	async update(id, input) {
+		const validated = this.deserializeUpdate(input);
+		const prepared = await this.beforeUpdate(id, validated);
+		const updated = await this.getManager().update(id, prepared);
+		return this.toRepresentation(updated);
+	}
+	/**
+	* Override to normalize create input for this resource workflow before the
+	* manager call.
+	*
+	* Model-owned persistence rules belong in model hooks so they also run for
+	* scripts and direct manager usage.
+	*/
+	async beforeCreate(data) {
+		return data;
+	}
+	/**
+	* Override to normalize update input for this resource workflow before the
+	* manager call.
+	*
+	* Model-owned persistence rules belong in model hooks so they also run for
+	* scripts and direct manager usage.
+	*/
+	async beforeUpdate(_id, data) {
+		return data;
+	}
+};
+
+//#endregion
+//#region src/serializer/index.ts
+var serializer_exports = {};
+__export(serializer_exports, {
+	ModelSerializer: () => ModelSerializer,
+	Serializer: () => Serializer
+});
+
 //#endregion
 //#region src/viewset/ModelViewSet.ts
 var ModelViewSet = class ModelViewSet {
 	static BRAND = "tango.resources.model_view_set";
-	repository;
-	readSchema;
-	writeSchema;
-	updateSchema;
+	static actions = [];
+	__tangoBrand = ModelViewSet.BRAND;
+	serializerClass;
 	filters;
 	orderingFields;
 	searchFields;
-	__tangoBrand = ModelViewSet.BRAND;
-	static isModelViewSet(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === ModelViewSet.BRAND;
-	}
+	paginatorFactory;
+	serializer;
 	constructor(config) {
-		this.repository = config.repository;
-		this.readSchema = config.readSchema;
-		this.writeSchema = config.writeSchema;
-		this.updateSchema = config.updateSchema ?? config.writeSchema.partial();
+		this.serializerClass = config.serializer;
 		this.filters = config.filters;
 		this.orderingFields = config.orderingFields ?? [];
 		this.searchFields = config.searchFields ?? [];
+		this.paginatorFactory = config.paginatorFactory;
+	}
+	/**
+	* Return the custom action descriptors declared by a viewset or constructor.
+	*/
+	static getActions(viewsetOrConstructor) {
+		const viewset = ModelViewSet.isModelViewSet(viewsetOrConstructor) ? viewsetOrConstructor : null;
+		const constructorValue = viewset ? viewset.constructor : viewsetOrConstructor;
+		const actions = Array.isArray(constructorValue.actions) ? constructorValue.actions : [];
+		return actions.map((action) => ({
+			...action,
+			path: viewset ? viewset.resolveActionPath(action) : ModelViewSet.resolvePathFromDescriptor(action.name, action.path)
+		}));
+	}
+	/**
+	* Narrow an unknown value to `ModelViewSet`.
+	*/
+	static isModelViewSet(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === ModelViewSet.BRAND;
+	}
+	/**
+	* Preserve literal action inference while validating the descriptor shape.
+	*/
+	static defineViewSetActions(actions) {
+		return actions;
+	}
+	static resolvePathFromDescriptor(name, explicitPath) {
+		const normalized = (explicitPath?.trim() || ModelViewSet.toKebabCase(name)).replace(/^\/+|\/+$/g, "");
+		if (!normalized) throw new Error(`Invalid custom action path for '${name}'.`);
+		return normalized;
+	}
+	static toKebabCase(input) {
+		return input.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+	}
+	/**
+	* Return the serializer class that owns this resource contract.
+	*/
+	getSerializerClass() {
+		return this.serializerClass;
 	}
+	/**
+	* Return the serializer instance for the current resource.
+	*/
+	getSerializer() {
+		if (!this.serializer) this.serializer = new this.serializerClass();
+		return this.serializer;
+	}
+	/**
+	* Describe the public HTTP contract that this resource contributes to OpenAPI generation.
+	*/
+	describeOpenAPI() {
+		return {
+			model: this.requireModelMetadata(),
+			outputSchema: this.getSerializer().getOutputSchema(),
+			createSchema: this.getSerializer().getCreateSchema(),
+			updateSchema: this.getSerializer().getUpdateSchema(),
+			searchFields: this.searchFields,
+			orderingFields: this.orderingFields,
+			lookupField: this.getManager().meta.pk,
+			lookupParam: "id",
+			allowedMethods: [
+				"GET",
+				"POST",
+				"PUT",
+				"PATCH",
+				"DELETE"
+			],
+			usesDefaultOffsetPagination: !this.paginatorFactory,
+			actions: ModelViewSet.getActions(this)
+		};
+	}
+	/**
+	* List endpoint with filtering, search, ordering, and offset pagination.
+	*/
 	async list(ctx) {
 		try {
-			const params = new URL(ctx.request.url).searchParams;
-			const paginator = new OffsetPaginator(this.repository.query());
+			const params = ctx.request.queryParams;
+			const baseQueryset = this.getManager().query();
+			const paginator = this.getPaginator(baseQueryset);
 			paginator.parse(params);
-			let qs = this.repository.query();
+			let qs = baseQueryset;
 			if (this.filters) {
 				const filterInputs = this.filters.apply(params);
 				if (filterInputs.length > 0) qs = qs.filter(Q.and(...filterInputs));
 			}
-			const search = params.get("search");
+			const search = params.getSearch();
 			if (search && this.searchFields.length > 0) {
 				const searchFilters = this.searchFields.map((field) => {
 					const lookup = `${String(field)}__icontains`;
@@ -418,86 +717,102 @@ var ModelViewSet = class ModelViewSet {
 				});
 				qs = qs.filter(Q.or(...searchFilters));
 			}
-			const ordering = params.get("ordering");
-			if (ordering) {
-				const orderTokens = ordering.split(",").filter((field) => {
+			const ordering = params.getOrdering();
+			if (ordering.length > 0) {
+				const orderTokens = ordering.filter((field) => {
 					const cleanField = field.startsWith("-") ? field.slice(1) : field;
 					return this.orderingFields.includes(cleanField);
 				});
 				if (orderTokens.length > 0) qs = qs.orderBy(...orderTokens.map((token) => token));
 			}
 			qs = paginator.apply(qs);
-			const [result, totalCount] = await Promise.all([qs.fetch(this.readSchema), qs.count()]);
-			const response = paginator.toResponse(result.results, { totalCount });
-			return new Response(JSON.stringify(response), {
-				status: 200,
-				headers: { "Content-Type": "application/json" }
-			});
+			const resultPromise = qs.fetch();
+			const totalCountPromise = paginator.needsTotalCount() ? qs.count() : Promise.resolve(undefined);
+			const [result, totalCount] = await Promise.all([resultPromise, totalCountPromise]);
+			const serializer = this.getSerializer();
+			const response = paginator.toResponse(result.results.map((row) => serializer.toRepresentation(row)), { totalCount });
+			return TangoResponse.json(response, { status: 200 });
 		} catch (error) {
 			return this.handleError(error);
 		}
 	}
+	/**
+	* Retrieve endpoint for a single resource by id.
+	*/
 	async retrieve(_ctx, id) {
 		try {
-			const pk = this.repository.meta.pk;
+			const manager = this.getManager();
+			const pk = manager.meta.pk;
 			const filterById = { [pk]: id };
-			const result = await this.repository.query().filter(filterById).fetchOne(this.readSchema);
-			if (!result) return new Response(JSON.stringify({ error: "Not found" }), {
-				status: 404,
-				headers: { "Content-Type": "application/json" }
-			});
-			return new Response(JSON.stringify(result), {
-				status: 200,
-				headers: { "Content-Type": "application/json" }
-			});
+			const result = await manager.query().filter(filterById).fetchOne();
+			if (!result) throw new NotFoundError(`No ${manager.meta.table} record found for ${String(pk)}=${id}.`);
+			return TangoResponse.json(this.getSerializer().toRepresentation(result), { status: 200 });
 		} catch (error) {
 			return this.handleError(error);
 		}
 	}
+	/**
+	* Create endpoint: validate input, persist, and return serialized output.
+	*/
 	async create(ctx) {
 		try {
 			const body = await ctx.request.json();
-			const validated = this.writeSchema.parse(body);
-			const created = await this.repository.create(validated);
-			const result = this.readSchema.parse(created);
-			return new Response(JSON.stringify(result), {
-				status: 201,
-				headers: { "Content-Type": "application/json" }
-			});
+			const result = await this.getSerializer().create(body);
+			return TangoResponse.created(undefined, result);
 		} catch (error) {
 			return this.handleError(error);
 		}
 	}
+	/**
+	* Update endpoint: validate partial payload and persist by id.
+	*/
 	async update(ctx, id) {
 		try {
 			const body = await ctx.request.json();
-			const validated = this.updateSchema.parse(body);
 			const pkValue = id;
-			const updated = await this.repository.update(pkValue, validated);
-			const result = this.readSchema.parse(updated);
-			return new Response(JSON.stringify(result), {
-				status: 200,
-				headers: { "Content-Type": "application/json" }
-			});
+			const result = await this.getSerializer().update(pkValue, body);
+			return TangoResponse.json(result, { status: 200 });
 		} catch (error) {
 			return this.handleError(error);
 		}
 	}
+	/**
+	* Destroy endpoint: delete a resource by id.
+	*/
 	async destroy(_ctx, id) {
 		try {
 			const pkValue = id;
-			await this.repository.delete(pkValue);
-			return new Response(null, { status: 204 });
+			await this.getManager().delete(pkValue);
+			return TangoResponse.noContent();
 		} catch (error) {
 			return this.handleError(error);
 		}
 	}
+	getPaginator(queryset) {
+		if (this.paginatorFactory) return this.paginatorFactory(queryset);
+		return new OffsetPaginator(queryset);
+	}
+	getManager() {
+		return this.getSerializer().getManager();
+	}
+	/**
+	* Convert thrown errors into normalized HTTP responses.
+	*/
 	handleError(error) {
-		const httpError = toHttpError(error);
-		return new Response(JSON.stringify(httpError.body), {
-			status: httpError.status,
-			headers: { "Content-Type": "application/json" }
-		});
+		const httpError = HttpErrorFactory.toHttpError(error);
+		return TangoResponse.json(httpError.body, { status: httpError.status });
+	}
+	/**
+	* Resolve route path segment(s) for a custom action.
+	* Override this in subclasses to customize path derivation globally.
+	*/
+	resolveActionPath(action) {
+		return ModelViewSet.resolvePathFromDescriptor(action.name, action.path);
+	}
+	requireModelMetadata() {
+		const model = this.getSerializer().getModel();
+		if (!model.metadata) throw new Error("OpenAPI generation requires Tango model metadata on ModelViewSet models.");
+		return model;
 	}
 };
 
@@ -507,10 +822,5 @@ var viewset_exports = {};
 __export(viewset_exports, { ModelViewSet: () => ModelViewSet });
 
 //#endregion
-//#region src/domain/index.ts
-var domain_exports = {};
-__export(domain_exports, { PaginationInput: () => PaginationInput });
-
-//#endregion
-export { CursorPaginator, FilterSet, ModelViewSet, OffsetPaginator, PaginationInput, RequestContext, context_exports as context, domain_exports as domain, filters_exports as filters, pagination_exports as pagination, paginators_exports as paginators, viewset_exports as viewset };
+export { APIView, CreateAPIView, CreateModelMixin, CursorPaginationInput, CursorPaginator, DestroyModelMixin, FilterSet, GenericAPIView, ListAPIView, ListCreateAPIView, ListModelMixin, ModelSerializer, ModelViewSet, OffsetPaginationInput, OffsetPaginator, RequestContext, RetrieveAPIView, RetrieveDestroyAPIView, RetrieveModelMixin, RetrieveUpdateAPIView, RetrieveUpdateDestroyAPIView, Serializer, UpdateModelMixin, context_exports as context, filters_exports as filters, pagination_exports as pagination, paginators_exports as paginators, resource_exports as resource, serializer_exports as serializer, view_exports as view, viewset_exports as viewset };
 //# sourceMappingURL=index.js.map