@danceroutine/tango-resources 1.7.0 → 1.8.0

package/dist/filters/FilterSet.d.ts

@@ -2,23 +2,24 @@ import { TangoQueryParams } from '@danceroutine/tango-core';
 import type { FilterInput, FilterValue, LookupType } from '@danceroutine/tango-orm';
 import { InternalFilterType } from './internal/InternalFilterType';
 import type { RangeOperator } from './RangeOperator';
+type FilterFieldRef<T extends Record<string, unknown>> = Extract<keyof T, string> | string;
 /**
  * Configuration for how a query parameter should be resolved into a filter.
  * Supports scalar equality, case-insensitive search, range comparisons, IN queries, and custom logic.
  */
-export type FilterResolver<T> = {
+export type FilterResolver<T extends Record<string, unknown>> = {
     type: typeof InternalFilterType.SCALAR;
-    column: keyof T;
+    column: FilterFieldRef<T>;
 } | {
     type: typeof InternalFilterType.ILIKE;
-    columns: (keyof T)[];
+    columns: FilterFieldRef<T>[];
 } | {
     type: typeof InternalFilterType.RANGE;
-    column: keyof T;
+    column: FilterFieldRef<T>;
     op: RangeOperator;
 } | {
     type: typeof InternalFilterType.IN;
-    column: keyof T;
+    column: FilterFieldRef<T>;
 } | {
     type: typeof InternalFilterType.CUSTOM;
     apply: (value: string | string[] | undefined) => FilterInput<T> | undefined;
@@ -31,18 +32,18 @@ export type FieldFilterDeclaration = true | readonly FilterLookup[] | {
     parse?: FilterValueParser;
 };
 export type AliasFilterDeclaration<T extends Record<string, unknown>> = FilterResolver<T> | {
-    field: keyof T;
+    field: FilterFieldRef<T>;
     lookup?: FilterLookup;
     parse?: FilterValueParser;
 } | {
-    fields: readonly (keyof T)[];
+    fields: readonly FilterFieldRef<T>[];
     lookup?: FilterLookup;
     parse?: FilterValueParser;
 };
 export interface FilterSetDefineConfig<T extends Record<string, unknown>> {
-    fields?: Partial<Record<keyof T, FieldFilterDeclaration>>;
+    fields?: Partial<Record<string, FieldFilterDeclaration>>;
     aliases?: Record<string, AliasFilterDeclaration<T>>;
-    parsers?: Partial<Record<keyof T, FilterValueParser>>;
+    parsers?: Partial<Record<string, FilterValueParser>>;
     all?: '__all__';
 }
 /**
@@ -82,7 +83,7 @@ export declare class FilterSet<T extends Record<string, unknown>> {
     /**
      * Return a new filter set with parser-aware scalar/range/in resolvers for matching fields.
      */
-    withFieldParsers(parsers: Partial<Record<keyof T, FilterValueParser>>): FilterSet<T>;
+    withFieldParsers(parsers: Partial<Record<string, FilterValueParser>>): FilterSet<T>;
     /**
      * Apply all configured resolvers against query params.
      */
@@ -91,3 +92,4 @@ export declare class FilterSet<T extends Record<string, unknown>> {
     private resolveFilter;
     private applyFieldParserOverride;
 }
+export {};

package/dist/filters/internal/InternalFilterLookup.d.ts

@@ -0,0 +1,15 @@
+export declare const InternalFilterLookup: {
+    readonly EXACT: "exact";
+    readonly LT: "lt";
+    readonly LTE: "lte";
+    readonly GT: "gt";
+    readonly GTE: "gte";
+    readonly IN: "in";
+    readonly ISNULL: "isnull";
+    readonly CONTAINS: "contains";
+    readonly ICONTAINS: "icontains";
+    readonly STARTSWITH: "startswith";
+    readonly ISTARTSWITH: "istartswith";
+    readonly ENDSWITH: "endswith";
+    readonly IENDSWITH: "iendswith";
+};

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { BaseUser } from './context/index';
 export { FilterSet, type AliasFilterDeclaration, type FieldFilterDeclaration, type FilterLookup, type FilterResolver, type FilterSetDefineConfig, type FilterValueParser, } from './filters/index';
 export type { FilterType, RangeOperator } from './filters/index';
 export { CursorPaginator, OffsetPaginator, CursorPaginationInput, OffsetPaginationInput, type Page, type BasePaginatedResponse, type CursorPaginatedResponse, type OffsetPaginatedResponse, type PaginatedResponse, type Paginator, } from './pagination/index';
-export { Serializer, ModelSerializer, type SerializerClass, type AnySerializerClass, type SerializerCreateInput, type SerializerUpdateInput, type SerializerOutput, type SerializerSchema, type ModelSerializerClass, type AnyModelSerializerClass, } from './serializer/index';
+export { Serializer, ModelSerializer, relation, type SerializerClass, type AnySerializerClass, type SerializerCreateInput, type SerializerUpdateInput, type SerializerOutput, type SerializerSchema, type ModelSerializerClass, type AnyModelSerializer, type AnyModelSerializerClass, type ModelSerializerRelationFields, type ManyToManyManagerKeys, type ManyToManyRelationField, type ManyToManyReadStrategy, type ManyToManyWriteStrategy, } from './serializer/index';
 export { ModelViewSet } from './viewset/index';
 export type { ModelViewSetOpenAPIDescription, ModelViewSetConfig, ViewSetActionDescriptor, ViewSetActionMethod, ViewSetActionScope, ResolvedViewSetActionDescriptor, } from './viewset/index';
 export { APIView, GenericAPIView, ListModelMixin, CreateModelMixin, RetrieveModelMixin, UpdateModelMixin, DestroyModelMixin, ListAPIView, CreateAPIView, RetrieveAPIView, ListCreateAPIView, RetrieveUpdateAPIView, RetrieveDestroyAPIView, RetrieveUpdateDestroyAPIView, } from './view/index';

package/dist/index.js

@@ -1,6 +1,6 @@
-import { APIView, BasePaginator, CreateAPIView, CreateModelMixin, DestroyModelMixin, GenericAPIView, ListAPIView, ListCreateAPIView, ListModelMixin, OffsetPaginationInput, OffsetPaginator, RetrieveAPIView, RetrieveDestroyAPIView, RetrieveModelMixin, RetrieveUpdateAPIView, RetrieveUpdateDestroyAPIView, UpdateModelMixin, __export, inferModelFieldParsers, view_exports } from "./view-Djm3cQ6C.js";
-import { HttpErrorFactory, NotFoundError, TangoRequest, TangoResponse } from "@danceroutine/tango-core";
-import { Q } from "@danceroutine/tango-orm";
+import { APIView, BasePaginator, CreateAPIView, CreateModelMixin, DestroyModelMixin, GenericAPIView, ListAPIView, ListCreateAPIView, ListModelMixin, OffsetPaginationInput, OffsetPaginator, RetrieveAPIView, RetrieveDestroyAPIView, RetrieveModelMixin, RetrieveUpdateAPIView, RetrieveUpdateDestroyAPIView, UpdateModelMixin, __export, inferModelFieldParsers, view_exports } from "./view-iXGdHuS-.js";
+import { HttpErrorFactory, NotFoundError, TangoRequest, TangoResponse, getLogger } from "@danceroutine/tango-core";
+import { ManyToManyRelatedManager, Q } from "@danceroutine/tango-orm";
 import { z, z as z$1 } from "zod";
 
 //#region src/context/RequestContext.ts
@@ -68,8 +68,30 @@ const InternalFilterType = {
 	CUSTOM: "custom"
 };
 
+//#endregion
+//#region src/filters/internal/InternalFilterLookup.ts
+const InternalFilterLookup = {
+	EXACT: "exact",
+	LT: "lt",
+	LTE: "lte",
+	GT: "gt",
+	GTE: "gte",
+	IN: "in",
+	ISNULL: "isnull",
+	CONTAINS: "contains",
+	ICONTAINS: "icontains",
+	STARTSWITH: "startswith",
+	ISTARTSWITH: "istartswith",
+	ENDSWITH: "endswith",
+	IENDSWITH: "iendswith"
+};
+
 //#endregion
 //#region src/filters/FilterSet.ts
+const FILTER_LOOKUPS = Object.values(InternalFilterLookup);
+function isFilterLookup(value) {
+	return FILTER_LOOKUPS.includes(value);
+}
 var FilterSet = class FilterSet {
 	static BRAND = "tango.resources.filter_set";
 	__tangoBrand = FilterSet.BRAND;
@@ -109,7 +131,7 @@ var FilterSet = class FilterSet {
 	}
 	static addFieldDeclaration(spec, field, declaration, parser) {
 		if (declaration === true) {
-			spec[String(field)] = FilterSet.createLookupResolver(field, "exact", parser);
+			spec[String(field)] = FilterSet.createLookupResolver(field, InternalFilterLookup.EXACT, parser);
 			return;
 		}
 		if (FilterSet.isLookupArray(declaration)) {
@@ -119,7 +141,7 @@ var FilterSet = class FilterSet {
 			}
 			return;
 		}
-		const lookups = declaration.lookups ?? ["exact"];
+		const lookups = declaration.lookups ?? [InternalFilterLookup.EXACT];
 		const baseParam = declaration.param ?? String(field);
 		const effectiveParser = declaration.parse ?? parser;
 		for (const lookup of lookups) {
@@ -133,10 +155,10 @@ var FilterSet = class FilterSet {
 	static normalizeAliasDeclaration(declaration) {
 		if (FilterSet.isFilterResolverDeclaration(declaration)) return declaration;
 		if ("fields" in declaration) {
-			const lookup = declaration.lookup ?? "icontains";
+			const lookup = declaration.lookup ?? InternalFilterLookup.ICONTAINS;
 			return FilterSet.createMultiFieldResolver(declaration.fields, lookup, declaration.parse);
 		}
-		return FilterSet.createLookupResolver(declaration.field, declaration.lookup ?? "exact", declaration.parse);
+		return FilterSet.createLookupResolver(declaration.field, declaration.lookup ?? InternalFilterLookup.EXACT, declaration.parse);
 	}
 	static isFilterResolverDeclaration(value) {
 		if (typeof value !== "object" || value === null || !("type" in value)) return false;
@@ -149,7 +171,7 @@ var FilterSet = class FilterSet {
 		].includes(value.type);
 	}
 	static createMultiFieldResolver(fields, lookup, parser) {
-		if (lookup === "icontains" && parser === undefined) return {
+		if (lookup === InternalFilterLookup.ICONTAINS && parser === undefined) return {
 			type: InternalFilterType.ILIKE,
 			columns: [...fields]
 		};
@@ -264,14 +286,16 @@ var FilterSet = class FilterSet {
 		return filters;
 	}
 	buildAllResolver(param) {
-		const [rawField, ...rawLookupParts] = param.split("__");
-		if (!rawField) return undefined;
-		const field = rawField;
-		if (rawLookupParts.length === 0) return {
+		const segments = param.split("__").filter(Boolean);
+		if (segments.length === 0) return undefined;
+		const lastSegment = segments.at(-1);
+		const lookup = isFilterLookup(lastSegment) ? lastSegment : "exact";
+		const field = (lookup === "exact" ? segments : segments.slice(0, -1)).join("__");
+		if (!field) return undefined;
+		if (lookup === "exact") return {
 			type: InternalFilterType.SCALAR,
 			column: field
 		};
-		const lookup = rawLookupParts.join("__");
 		return FilterSet.createLookupResolver(field, lookup);
 	}
 	resolveFilter(resolver, value) {
@@ -525,10 +549,13 @@ var resource_exports = {};
 
 //#endregion
 //#region src/serializer/Serializer.ts
+const logger = getLogger("tango.resources.serializer");
+let hasWarnedAboutToRepresentationDeprecation = false;
 var Serializer = class {
 	static createSchema = z.unknown();
 	static updateSchema = z.unknown();
 	static outputSchema = z.unknown();
+	static outputResolvers = undefined;
 	/**
 	* Return the serializer class for the current instance.
 	*/
@@ -554,6 +581,13 @@ var Serializer = class {
 		return this.getSerializerClass().outputSchema;
 	}
 	/**
+	* Return the resolver map used to enrich serializer output fields before
+	* the outward Zod schema parses the final response shape.
+	*/
+	getOutputResolvers() {
+		return this.getSerializerClass().outputResolvers ?? {};
+	}
+	/**
 	* Validate unknown input for create workflows.
 	*/
 	deserializeCreate(input) {
@@ -567,16 +601,59 @@ var Serializer = class {
 	}
 	/**
 	* Convert a persisted record into its outward-facing representation.
+	*
+	* @deprecated Use `serialize(...)` instead so serializer-owned output
+	* resolvers run before the outward Zod schema parses the response shape.
 	*/
 	toRepresentation(record) {
+		if (!hasWarnedAboutToRepresentationDeprecation) {
+			hasWarnedAboutToRepresentationDeprecation = true;
+			logger.warn("`Serializer.toRepresentation(...)` is deprecated. Use `serialize(...)` instead so output resolvers run before outward parsing.");
+		}
 		return this.getOutputSchema().parse(record);
 	}
+	/**
+	* Resolve serializer-owned output fields and parse the outward response
+	* contract.
+	*/
+	async serialize(record) {
+		return this.getOutputSchema().parse(await this.applyOutputResolvers(record));
+	}
+	/**
+	* Serialize many records through the same outward response contract.
+	*/
+	async serializeMany(records) {
+		return Promise.all(records.map((record) => this.serialize(record)));
+	}
+	async applyOutputResolvers(record) {
+		const resolvers = this.getOutputResolvers();
+		const resolverEntries = Object.entries(resolvers);
+		if (resolverEntries.length === 0 || typeof record !== "object" || record === null) return record;
+		const resolved = await Promise.all(resolverEntries.map(async ([key, resolver]) => [key, await resolver(record)]));
+		return {
+			...record,
+			...Object.fromEntries(resolved)
+		};
+	}
+};
+
+//#endregion
+//#region src/serializer/internal/InternalSerializerRelationKind.ts
+const InternalSerializerRelationKind = { MANY_TO_MANY: "manyToMany" };
+const InternalManyToManyReadStrategyKind = {
+	PK_LIST: "pkList",
+	NESTED: "nested"
+};
+const InternalManyToManyWriteStrategyKind = {
+	PK_LIST: "pkList",
+	SLUG_LIST: "slugList"
 };
 
 //#endregion
 //#region src/serializer/ModelSerializer.ts
 var ModelSerializer = class extends Serializer {
 	static model;
+	static relationFields = undefined;
 	/**
 	* Return the Tango model backing this serializer.
 	*/
@@ -592,22 +669,44 @@ var ModelSerializer = class extends Serializer {
 		return this.getModel().objects;
 	}
 	/**
+	* Return the declarative relation-field map for this serializer.
+	*/
+	getRelationFields() {
+		return this.constructor.relationFields ?? {};
+	}
+	/**
+	* Merge relation-field read resolvers into the serializer output path.
+	*/
+	getOutputResolvers() {
+		const baseResolvers = super.getOutputResolvers();
+		const relationFields = this.getRelationFields();
+		const relationResolvers = Object.fromEntries(Object.entries(relationFields).map(([fieldName, field]) => [fieldName, async (record) => this.serializeRelationField(record, fieldName, field)]));
+		return {
+			...relationResolvers,
+			...baseResolvers
+		};
+	}
+	/**
 	* Validate, enrich, persist, and serialize a create workflow.
 	*/
 	async create(input) {
 		const validated = this.deserializeCreate(input);
+		const relationWrites = this.extractRelationWrites(validated, input);
 		const prepared = await this.beforeCreate(validated);
-		const created = await this.getManager().create(prepared);
-		return this.toRepresentation(created);
+		const created = await this.getManager().create(this.stripRelationFields(prepared));
+		await this.applyRelationWrites(created, relationWrites);
+		return this.serialize(created);
 	}
 	/**
 	* Validate, enrich, persist, and serialize an update workflow.
 	*/
 	async update(id, input) {
 		const validated = this.deserializeUpdate(input);
+		const relationWrites = this.extractRelationWrites(validated, input);
 		const prepared = await this.beforeUpdate(id, validated);
-		const updated = await this.getManager().update(id, prepared);
-		return this.toRepresentation(updated);
+		const updated = await this.getManager().update(id, this.stripRelationFields(prepared));
+		await this.applyRelationWrites(updated, relationWrites);
+		return this.serialize(updated);
 	}
 	/**
 	* Override to normalize create input for this resource workflow before the
@@ -629,6 +728,113 @@ var ModelSerializer = class extends Serializer {
 	async beforeUpdate(_id, data) {
 		return data;
 	}
+	extractRelationWrites(data, rawInput) {
+		if (typeof data !== "object" || data === null || typeof rawInput !== "object" || rawInput === null) return {};
+		const relationFields = this.getRelationFields();
+		const writes = {};
+		for (const fieldName of Object.keys(relationFields)) if (fieldName in rawInput) writes[fieldName] = data[fieldName];
+		return writes;
+	}
+	stripRelationFields(data) {
+		const relationFieldNames = new Set(Object.keys(this.getRelationFields()));
+		if (relationFieldNames.size === 0) return data;
+		return Object.fromEntries(Object.entries(data).filter(([fieldName]) => !relationFieldNames.has(fieldName)));
+	}
+	async applyRelationWrites(record, writes) {
+		const relationFields = this.getRelationFields();
+		for (const [fieldName, value] of Object.entries(writes)) {
+			const field = relationFields[fieldName];
+			if (!field) continue;
+			await this.syncManyToManyRelation(record, fieldName, value);
+		}
+	}
+	async serializeRelationField(record, fieldName, field) {
+		const manager = this.getManyToManyManager(record, fieldName);
+		const rows = (await manager.all().fetch()).results;
+		const relationMeta = this.getManyToManyRelationMeta(fieldName);
+		switch (field.read.kind) {
+			case InternalManyToManyReadStrategyKind.PK_LIST: return rows.map((row) => row[relationMeta.targetPrimaryKey]);
+			case InternalManyToManyReadStrategyKind.NESTED: return rows.map((row) => field.read.schema.parse(row));
+		}
+	}
+	async syncManyToManyRelation(record, fieldName, value) {
+		if (value === undefined) return;
+		const manager = this.getManyToManyManager(record, fieldName);
+		const field = this.getRelationFields()[fieldName];
+		if (!field) return;
+		const nextTargets = await this.resolveWriteTargets(fieldName, field.write, value);
+		const currentTargets = (await manager.all().fetch()).results;
+		if (currentTargets.length > 0) await manager.remove(...currentTargets);
+		if (nextTargets.length > 0) await manager.add(...nextTargets);
+	}
+	async resolveWriteTargets(fieldName, strategy, value) {
+		switch (strategy.kind) {
+			case InternalManyToManyWriteStrategyKind.PK_LIST:
+				if (!Array.isArray(value)) throw new TypeError(`Relation field '${String(fieldName)}' expects an array of primary-key values.`);
+				return value;
+			case InternalManyToManyWriteStrategyKind.SLUG_LIST: {
+				if (!Array.isArray(value)) throw new TypeError(`Relation field '${String(fieldName)}' expects an array of lookup values.`);
+				const lookupValues = [...new Set(value.map((entry) => String(entry).trim()).filter(Boolean))];
+				if (lookupValues.length === 0) return [];
+				const filter = { [`${strategy.lookupField}__in`]: lookupValues };
+				const existing = await strategy.model.objects.query().filter(filter).fetch();
+				const byLookup = new Map(existing.results.map((row) => [String(row[strategy.lookupField]), row]));
+				const resolved = [];
+				for (const lookupValue of lookupValues) {
+					const found = byLookup.get(lookupValue);
+					if (found) {
+						resolved.push(found);
+						continue;
+					}
+					if (!strategy.createIfMissing) throw new Error(`Relation field '${String(fieldName)}' could not resolve '${lookupValue}' via '${strategy.lookupField}'.`);
+					const created = await strategy.model.objects.create(strategy.buildCreateInput?.(lookupValue) ?? { [strategy.lookupField]: lookupValue });
+					resolved.push(created);
+				}
+				return resolved;
+			}
+		}
+	}
+	getManyToManyManager(record, fieldName) {
+		const manager = record[fieldName];
+		if (!ManyToManyRelatedManager.isManyToManyRelatedManager(manager)) throw new Error(`Relation field '${fieldName}' is not backed by a many-to-many related manager.`);
+		return manager;
+	}
+	getManyToManyRelationMeta(fieldName) {
+		const relation$1 = this.getManager().meta.relations?.[fieldName];
+		if (!relation$1 || relation$1.kind !== InternalSerializerRelationKind.MANY_TO_MANY) throw new Error(`Relation field '${fieldName}' is not a persisted many-to-many edge.`);
+		return relation$1;
+	}
+};
+
+//#endregion
+//#region src/serializer/relation.ts
+function pkList() {
+	return { kind: InternalManyToManyReadStrategyKind.PK_LIST };
+}
+function nested(schema) {
+	return {
+		kind: InternalManyToManyReadStrategyKind.NESTED,
+		schema
+	};
+}
+function slugList(options) {
+	return {
+		kind: InternalManyToManyWriteStrategyKind.SLUG_LIST,
+		...options
+	};
+}
+function manyToMany(config = {}) {
+	return {
+		kind: InternalSerializerRelationKind.MANY_TO_MANY,
+		read: config.read ?? pkList(),
+		write: config.write ?? pkList()
+	};
+}
+const relation = {
+	manyToMany,
+	pkList,
+	nested,
+	slugList
 };
 
 //#endregion
@@ -636,7 +842,8 @@ var ModelSerializer = class extends Serializer {
 var serializer_exports = {};
 __export(serializer_exports, {
 	ModelSerializer: () => ModelSerializer,
-	Serializer: () => Serializer
+	Serializer: () => Serializer,
+	relation: () => relation
 });
 
 //#endregion
@@ -763,7 +970,8 @@ var ModelViewSet = class ModelViewSet {
 			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.map((row) => serializer.toRepresentation(row)), { totalCount });
+			const rows = await serializer.serializeMany(result.items);
+			const response = paginator.toResponse(rows, { totalCount });
 			return TangoResponse.json(response, { status: 200 });
 		} catch (error) {
 			return this.handleError(error);
@@ -779,7 +987,7 @@ var ModelViewSet = class ModelViewSet {
 			const filterById = { [pk]: id };
 			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 });
+			return TangoResponse.json(await this.getSerializer().serialize(result), { status: 200 });
 		} catch (error) {
 			return this.handleError(error);
 		}
@@ -860,5 +1068,5 @@ var viewset_exports = {};
 __export(viewset_exports, { ModelViewSet: () => ModelViewSet });
 
 //#endregion
-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 };
+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, relation, resource_exports as resource, serializer_exports as serializer, view_exports as view, viewset_exports as viewset };
 //# sourceMappingURL=index.js.map