@danceroutine/tango-resources 0.1.0 → 1.0.0

package/dist/viewset/ModelViewSet.d.ts

@@ -1,64 +1,110 @@
-import type { Repository } from '@danceroutine/tango-orm';
-import type { z } from 'zod';
+import type { ManagerLike, QuerySet } from '@danceroutine/tango-orm';
+import { TangoResponse } from '@danceroutine/tango-core';
 import type { RequestContext } from '../context/index';
 import type { FilterSet } from '../filters/index';
+import type { Paginator } from '../pagination/index';
+import type { ModelViewSetOpenAPIDescription } from '../resource/index';
+import type { AnyModelSerializerClass, ModelSerializerClass, SerializerOutput, SerializerSchema } from '../serializer/index';
+export type ViewSetActionScope = 'detail' | 'collection';
+export type ViewSetActionMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface ViewSetActionDescriptor {
+    name: string;
+    scope: ViewSetActionScope;
+    methods: readonly ViewSetActionMethod[];
+    path?: string;
+}
+export interface ResolvedViewSetActionDescriptor extends ViewSetActionDescriptor {
+    path: string;
+}
+type AnyModelViewSet = ModelViewSet<Record<string, unknown>, AnyModelSerializerClass>;
 /**
- * Configuration for a ModelViewSet, defining how a model is exposed as an API resource.
- *
- * @template TModel - The record type of the underlying database model
- * @template TRead - Zod schema used to validate and shape read (GET) responses
- * @template TWrite - Zod schema used to validate incoming write (POST/PUT) request bodies
- *
- * @example
- * ```typescript
- * const config: ModelViewSetConfig<Post, typeof PostReadSchema, typeof PostWriteSchema> = {
- *   repository: postRepository,
- *   readSchema: PostReadSchema,
- *   writeSchema: PostWriteSchema,
- *   updateSchema: PostPatchSchema,
- *   filters: postFilterSet,
- *   orderingFields: ['createdAt', 'title'],
- *   searchFields: ['title', 'body'],
- * };
- * ```
+ * Configuration for a ModelViewSet, defining how a serializer-backed model is exposed as an API resource.
  */
-export interface ModelViewSetConfig<TModel extends Record<string, unknown>, TRead extends z.ZodType, TWrite extends z.ZodObject<z.ZodRawShape>> {
-    /** The repository instance used to query and persist model data */
-    repository: Repository<TModel>;
-    /** Zod schema applied to outgoing data (list and detail responses) */
-    readSchema: TRead;
-    /** Zod schema applied to incoming data for create operations */
-    writeSchema: TWrite;
-    /** Optional Zod schema for partial updates (PATCH). Falls back to writeSchema if omitted */
-    updateSchema?: z.ZodType<Partial<TModel>>;
+export interface ModelViewSetConfig<TModel extends Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>> {
+    /** Serializer class that owns validation, representation, and persistence hooks */
+    serializer: TSerializer;
     /** Optional filter set defining which query parameters can filter the list endpoint */
     filters?: FilterSet<TModel>;
     /** Fields that clients are allowed to sort by via query parameters */
     orderingFields?: (keyof TModel)[];
     /** Fields that are searched when a free-text search query parameter is provided */
     searchFields?: (keyof TModel)[];
+    /** Optional paginator factory used by list endpoints. */
+    paginatorFactory?: (queryset: QuerySet<TModel>) => Paginator<TModel, SerializerOutput<TSerializer>>;
 }
 /**
  * Base class for creating RESTful API viewsets with built-in CRUD operations.
  * Provides list, retrieve, create, update, and delete methods with filtering,
  * search, pagination, and ordering support.
  */
-export declare abstract class ModelViewSet<TModel extends Record<string, unknown>, TRead extends z.ZodType, TWrite extends z.ZodObject<z.ZodRawShape>> {
+export declare abstract class ModelViewSet<TModel extends Record<string, unknown>, TSerializer extends ModelSerializerClass<TModel, SerializerSchema, SerializerSchema, SerializerSchema>> {
     static readonly BRAND: "tango.resources.model_view_set";
-    protected repository: Repository<TModel>;
-    protected readSchema: TRead;
-    protected writeSchema: TWrite;
-    protected updateSchema: z.ZodType<Partial<TModel>>;
-    protected filters?: FilterSet<TModel>;
-    protected orderingFields: (keyof TModel)[];
-    protected searchFields: (keyof TModel)[];
+    static readonly actions: readonly ViewSetActionDescriptor[];
     readonly __tangoBrand: typeof ModelViewSet.BRAND;
-    static isModelViewSet(value: unknown): value is ModelViewSet<Record<string, unknown>, z.ZodType, z.ZodObject<z.ZodRawShape>>;
-    constructor(config: ModelViewSetConfig<TModel, TRead, TWrite>);
-    list(ctx: RequestContext): Promise<Response>;
-    retrieve(_ctx: RequestContext, id: string): Promise<Response>;
-    create(ctx: RequestContext): Promise<Response>;
-    update(ctx: RequestContext, id: string): Promise<Response>;
-    destroy(_ctx: RequestContext, id: string): Promise<Response>;
-    protected handleError(error: unknown): Response;
+    protected readonly serializerClass: TSerializer;
+    protected readonly filters?: FilterSet<TModel>;
+    protected readonly orderingFields: (keyof TModel)[];
+    protected readonly searchFields: (keyof TModel)[];
+    protected readonly paginatorFactory?: (queryset: QuerySet<TModel>) => Paginator<TModel, SerializerOutput<TSerializer>>;
+    private serializer?;
+    constructor(config: ModelViewSetConfig<TModel, TSerializer>);
+    /**
+     * Return the custom action descriptors declared by a viewset or constructor.
+     */
+    static getActions(viewsetOrConstructor: AnyModelViewSet | (new (...args: never[]) => AnyModelViewSet)): readonly ResolvedViewSetActionDescriptor[];
+    /**
+     * Narrow an unknown value to `ModelViewSet`.
+     */
+    static isModelViewSet(value: unknown): value is ModelViewSet<Record<string, unknown>, AnyModelSerializerClass>;
+    /**
+     * Preserve literal action inference while validating the descriptor shape.
+     */
+    static defineViewSetActions<const T extends readonly ViewSetActionDescriptor[]>(actions: T): T;
+    private static resolvePathFromDescriptor;
+    private static toKebabCase;
+    /**
+     * Return the serializer class that owns this resource contract.
+     */
+    getSerializerClass(): TSerializer;
+    /**
+     * Return the serializer instance for the current resource.
+     */
+    getSerializer(): InstanceType<TSerializer>;
+    /**
+     * Describe the public HTTP contract that this resource contributes to OpenAPI generation.
+     */
+    describeOpenAPI(): ModelViewSetOpenAPIDescription<TModel, TSerializer>;
+    /**
+     * List endpoint with filtering, search, ordering, and offset pagination.
+     */
+    list(ctx: RequestContext): Promise<TangoResponse>;
+    /**
+     * Retrieve endpoint for a single resource by id.
+     */
+    retrieve(_ctx: RequestContext, id: string): Promise<TangoResponse>;
+    /**
+     * Create endpoint: validate input, persist, and return serialized output.
+     */
+    create(ctx: RequestContext): Promise<TangoResponse>;
+    /**
+     * Update endpoint: validate partial payload and persist by id.
+     */
+    update(ctx: RequestContext, id: string): Promise<TangoResponse>;
+    /**
+     * Destroy endpoint: delete a resource by id.
+     */
+    destroy(_ctx: RequestContext, id: string): Promise<TangoResponse>;
+    protected getPaginator(queryset: QuerySet<TModel>): Paginator<TModel, SerializerOutput<TSerializer>>;
+    protected getManager(): ManagerLike<TModel>;
+    /**
+     * Convert thrown errors into normalized HTTP responses.
+     */
+    protected handleError(error: unknown): TangoResponse;
+    /**
+     * Resolve route path segment(s) for a custom action.
+     * Override this in subclasses to customize path derivation globally.
+     */
+    protected resolveActionPath(action: ViewSetActionDescriptor): string;
+    private requireModelMetadata;
 }
+export {};

package/dist/viewset/index.d.ts

@@ -1,4 +1,5 @@
 /**
  * Domain boundary barrel: centralizes this subdomain's public contract.
  */
-export { ModelViewSet, type ModelViewSetConfig } from './ModelViewSet';
+export { ModelViewSet, type ModelViewSetConfig, type ViewSetActionDescriptor, type ViewSetActionMethod, type ViewSetActionScope, type ResolvedViewSetActionDescriptor, } from './ModelViewSet';
+export type { ModelViewSetOpenAPIDescription } from '../resource/index';

package/package.json

@@ -1,75 +1,81 @@
 {
-    "name": "@danceroutine/tango-resources",
-    "version": "0.1.0",
-    "description": "ModelViewSet, mixins, filters, and pagination for Tango",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./context": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./filters": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./pagination": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./paginators": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./viewset": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        },
-        "./domain": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js"
-        }
+  "name": "@danceroutine/tango-resources",
+  "version": "1.0.0",
+  "description": "ModelViewSet, serializers, filters, and pagination for Tango",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "files": [
-        "dist"
-    ],
-    "scripts": {
-        "build": "tsdown",
-        "test": "vitest run --coverage",
-        "test:watch": "vitest",
-        "typecheck": "tsc --noEmit"
+    "./context": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "keywords": [
-        "tango",
-        "resources",
-        "viewset",
-        "crud",
-        "rest"
-    ],
-    "author": "Pedro Del Moral Lopez",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/danceroutine/tango.git",
-        "directory": "packages/resources"
+    "./filters": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "dependencies": {
-        "@danceroutine/tango-core": "workspace:*",
-        "@danceroutine/tango-orm": "workspace:*",
-        "zod": "^4.0.0"
+    "./pagination": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "devDependencies": {
-        "@danceroutine/tango-schema": "workspace:*",
-        "@danceroutine/tango-testing": "workspace:*",
-        "@types/node": "^22.9.0",
-        "tsdown": "^0.4.0",
-        "typescript": "^5.6.3",
-        "vitest": "^4.0.6",
-        "zod": "^4.0.0"
+    "./paginators": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./serializer": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./viewset": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./view": {
+      "types": "./dist/view/index.d.ts",
+      "import": "./dist/view/index.js"
     }
-}
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "tango",
+    "resources",
+    "viewset",
+    "crud",
+    "rest"
+  ],
+  "author": "Pedro Del Moral Lopez",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danceroutine/tango.git",
+    "directory": "packages/resources"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@danceroutine/tango-core": "1.0.0",
+    "@danceroutine/tango-orm": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsdown": "^0.4.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.6",
+    "zod": "^4.0.0",
+    "@danceroutine/tango-testing": "1.0.0",
+    "@danceroutine/tango-schema": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "pnpm run typecheck:prod && pnpm run typecheck:test",
+    "typecheck:prod": "tsc --noEmit -p tsconfig.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.tests.json"
+  }
+}

package/dist/domain/index.d.ts

@@ -1,8 +0,0 @@
-/**
- * Compatibility aggregate barrel. Canonical source-of-truth types now live in
- * `filters`, `pagination`, and `viewset` subdomains.
- */
-export type { FilterType, RangeOperator } from '../filters/index';
-export type { ModelViewSetConfig } from '../viewset/index';
-export type { PaginatedResponse, Paginator, Page } from '../pagination/index';
-export { PaginationInput } from '../pagination/index';

package/dist/pagination/PaginationInput.d.ts

@@ -1,7 +0,0 @@
-import { z } from 'zod';
-export type PaginationInputValue = {
-    limit: number;
-    offset: number;
-    page?: number;
-};
-export declare const PaginationInput: z.ZodType<PaginationInputValue>;

package/dist/viewset/ModelViewSet.js

@@ -1,143 +0,0 @@
-import { OffsetPaginator } from '../paginators/OffsetPaginator';
-import { toHttpError } from '@danceroutine/tango-core';
-import { Q } from '@danceroutine/tango-orm';
-/**
- * Base class for creating RESTful API viewsets with built-in CRUD operations.
- * Provides list, retrieve, create, update, and delete methods with filtering,
- * search, pagination, and ordering support.
- */
-export class ModelViewSet {
-    static BRAND = 'tango.resources.model_view_set';
-    repository;
-    readSchema;
-    writeSchema;
-    updateSchema;
-    filters;
-    orderingFields;
-    searchFields;
-    __tangoBrand = ModelViewSet.BRAND;
-    static isModelViewSet(value) {
-        return (typeof value === 'object' &&
-            value !== null &&
-            value.__tangoBrand === ModelViewSet.BRAND);
-    }
-    constructor(config) {
-        this.repository = config.repository;
-        this.readSchema = config.readSchema;
-        this.writeSchema = config.writeSchema;
-        this.updateSchema = config.updateSchema ?? config.writeSchema.partial();
-        this.filters = config.filters;
-        this.orderingFields = config.orderingFields ?? [];
-        this.searchFields = config.searchFields ?? [];
-    }
-    async list(ctx) {
-        try {
-            const params = new URL(ctx.request.url).searchParams;
-            const paginator = new OffsetPaginator(this.repository.query());
-            paginator.parse(params);
-            let qs = this.repository.query();
-            if (this.filters) {
-                const filterInputs = this.filters.apply(params);
-                if (filterInputs.length > 0) {
-                    qs = qs.filter(Q.and(...filterInputs));
-                }
-            }
-            const search = params.get('search');
-            if (search && this.searchFields.length > 0) {
-                const searchFilters = this.searchFields.map((field) => {
-                    const lookup = `${String(field)}__icontains`;
-                    return { [lookup]: search };
-                });
-                qs = qs.filter(Q.or(...searchFilters));
-            }
-            const ordering = params.get('ordering');
-            if (ordering) {
-                const orderTokens = ordering.split(',').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' },
-            });
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    async retrieve(_ctx, id) {
-        try {
-            const pk = this.repository.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' },
-            });
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    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' },
-            });
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    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' },
-            });
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    async destroy(_ctx, id) {
-        try {
-            const pkValue = id;
-            await this.repository.delete(pkValue);
-            return new Response(null, { status: 204 });
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    handleError(error) {
-        const httpError = toHttpError(error);
-        return new Response(JSON.stringify(httpError.body), {
-            status: httpError.status,
-            headers: { 'Content-Type': 'application/json' },
-        });
-    }
-}