@danceroutine/tango-resources 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Del Moral Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @danceroutine/tango-resources
+
+`@danceroutine/tango-resources` provides Tango's API-layer primitives.
+
+The resources package turns model-backed data access into HTTP behavior. It gives application code a consistent way to express CRUD endpoints, custom API views, filtering, ordering, search, pagination, and serializer-backed request and response contracts while leaving request lifecycle ownership to adapters such as Express and Next.
+
+## Install
+
+```bash
+pnpm add @danceroutine/tango-resources
+```
+
+You will usually pair this package with `@danceroutine/tango-schema` and `@danceroutine/tango-orm`.
+
+## What the package does inside Tango
+
+The resource layer centers on four roles:
+
+- `APIView` and the generic API view classes for endpoints that are not full CRUD resources
+- `Serializer` and `ModelSerializer` for Zod-backed input validation, output representation, and resource-scoped normalization
+- `ModelViewSet` for CRUD APIs backed by a Tango serializer
+- filtering and pagination primitives that keep collection behavior consistent
+
+Model lifecycle hooks remain part of the persistence story through `@danceroutine/tango-schema`. A serializer shapes the resource contract. A model hook shapes the record lifecycle.
+
+Request query input reaches the resource layer through `TangoRequest.queryParams`, which exposes `TangoQueryParams` from `@danceroutine/tango-core`. That keeps filtering, search, ordering, and pagination behavior framework-agnostic while giving application code a public query helper it can reuse outside resources.
+
+## Quick start
+
+```ts
+import { z } from 'zod';
+import '@danceroutine/tango-orm/runtime';
+import { FilterSet, ModelSerializer, ModelViewSet } from '@danceroutine/tango-resources';
+import { Model, t } from '@danceroutine/tango-schema';
+
+const TodoReadSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    completed: z.coerce.boolean(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+const TodoCreateSchema = z.object({
+    title: z.string(),
+    completed: z.boolean().optional(),
+});
+const TodoUpdateSchema = TodoCreateSchema.partial();
+
+type Todo = z.output<typeof TodoReadSchema>;
+
+const TodoModel = Model({
+    namespace: 'app',
+    name: 'Todo',
+    schema: TodoReadSchema.extend({
+        id: t.primaryKey(z.number().int()),
+        title: z.string(),
+        completed: t.default(z.coerce.boolean(), 'false'),
+    }),
+    hooks: {
+        async beforeCreate({ data }) {
+            const now = new Date().toISOString();
+
+            return {
+                ...data,
+                createdAt: now,
+                updatedAt: now,
+            };
+        },
+        async beforeUpdate({ patch }) {
+            return {
+                ...patch,
+                updatedAt: new Date().toISOString(),
+            };
+        },
+    },
+});
+
+class TodoSerializer extends ModelSerializer<
+    Todo,
+    typeof TodoCreateSchema,
+    typeof TodoUpdateSchema,
+    typeof TodoReadSchema
+> {
+    static readonly model = TodoModel;
+    static readonly createSchema = TodoCreateSchema;
+    static readonly updateSchema = TodoUpdateSchema;
+    static readonly outputSchema = TodoReadSchema;
+}
+
+class TodoViewSet extends ModelViewSet<Todo, typeof TodoSerializer> {
+    constructor() {
+        super({
+            serializer: TodoSerializer,
+            filters: FilterSet.define<Todo>({
+                fields: { completed: true },
+            }),
+            orderingFields: ['id', 'title'],
+        });
+    }
+}
+```
+
+Adapters wire those resource classes to host routes through helpers such as `ExpressAdapter.registerViewSet(...)` and `NextAdapter.adaptViewSet(...)`.
+
+## Where logic belongs
+
+Use a serializer for:
+
+- create and update input validation
+- output representation
+- request-scoped normalization
+- resource-specific transformation that belongs to the HTTP contract
+
+Use model hooks for:
+
+- timestamp stamping
+- slug generation that must apply for every write path
+- persistence defaults and normalization that belong to the record itself
+- side effects that should run no matter which caller writes through `Model.objects`
+
+Use the resource or viewset for:
+
+- routing behavior
+- filtering, search, and pagination policy
+- custom actions and endpoint orchestration
+
+## Public API
+
+The root export includes:
+
+- `RequestContext`
+- `Serializer` and `ModelSerializer`
+- `FilterSet`
+- `OffsetPaginator`, `CursorPaginator`, and pagination contracts
+- `ModelViewSet`
+- `APIView`, `GenericAPIView`, and the generic CRUD-oriented view classes and mixins
+
+Most applications start with `ModelSerializer`, `ModelViewSet`, `FilterSet`, and one paginator. The generic view stack becomes useful when an endpoint is narrower than a full CRUD resource, and `APIView` stays available for fully custom request handling.
+
+## Import style
+
+The package supports both root imports and domain-style imports:
+
+```ts
+import { APIView, FilterSet, ModelSerializer, ModelViewSet, OffsetPaginator } from '@danceroutine/tango-resources';
+import { context, filters, pagination, serializer, view, viewset } from '@danceroutine/tango-resources';
+```
+
+Available subpaths include `context`, `filters`, `pagination`, `paginators`, `serializer`, `viewset`, `view`, and `domain`.
+
+## Developer workflow
+
+```bash
+pnpm --filter @danceroutine/tango-resources build
+pnpm --filter @danceroutine/tango-resources typecheck
+pnpm --filter @danceroutine/tango-resources test
+```
+
+## Bugs and support
+
+- Documentation: <https://tangowebframework.dev>
+- Serializers topic: <https://tangowebframework.dev/topics/serializers>
+- Model lifecycle hooks topic: <https://tangowebframework.dev/topics/model-lifecycle-hooks>
+- Resources topic: <https://tangowebframework.dev/topics/resources-and-viewsets>
+- API reference: <https://tangowebframework.dev/reference/resources-api>
+- Issue tracker: <https://github.com/danceroutine/tango/issues>
+
+## License
+
+MIT

package/dist/context/RequestContext.d.ts

@@ -1,3 +1,4 @@
+import { TangoRequest } from '@danceroutine/tango-core';
 /**
  * Default user shape for RequestContext.
  * Consumers can provide their own user type via the TUser generic parameter.
@@ -11,17 +12,35 @@ export interface BaseUser {
  * Generic over the user type so consumers can plug in their own auth infrastructure.
  */
 export declare class RequestContext<TUser = BaseUser> {
-    readonly request: Request;
+    readonly request: TangoRequest;
     user: TUser | null;
     params: Record<string, string>;
     static readonly BRAND: "tango.resources.request_context";
-    private state;
     readonly __tangoBrand: typeof RequestContext.BRAND;
-    constructor(request: Request, user?: TUser | null, params?: Record<string, string>);
+    private state;
+    constructor(request: TangoRequest, user?: TUser | null, params?: Record<string, string>);
+    /**
+     * Narrow an unknown value to `RequestContext`.
+     */
     static isRequestContext<TUser = BaseUser>(value: unknown): value is RequestContext<TUser>;
+    /**
+     * Construct a context with optional user payload.
+     */
+    static create<TUser = BaseUser>(request: Request, user?: TUser | null): RequestContext<TUser>;
+    /**
+     * Store arbitrary per-request state for downstream middleware/handlers.
+     */
     setState<T>(key: string | symbol, value: T): void;
+    /**
+     * Retrieve previously stored request state.
+     */
     getState<T>(key: string | symbol): T | undefined;
+    /**
+     * Check whether a state key has been set.
+     */
     hasState(key: string | symbol): boolean;
-    static create<TUser = BaseUser>(request: Request, user?: TUser | null): RequestContext<TUser>;
+    /**
+     * Clone the context, including route params and request-local state.
+     */
     clone(): RequestContext<TUser>;
 }

package/dist/filters/FilterSet.d.ts

@@ -1,4 +1,5 @@
-import type { FilterInput } from '@danceroutine/tango-orm';
+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';
 /**
@@ -22,12 +23,66 @@ export type FilterResolver<T> = {
     type: typeof InternalFilterType.CUSTOM;
     apply: (value: string | string[] | undefined) => FilterInput<T> | undefined;
 };
+export type FilterLookup = LookupType;
+export type FilterValueParser = (raw: string | string[]) => FilterValue | FilterValue[] | undefined;
+export type FieldFilterDeclaration = true | readonly FilterLookup[] | {
+    lookups?: readonly FilterLookup[];
+    param?: string;
+    parse?: FilterValueParser;
+};
+export type AliasFilterDeclaration<T extends Record<string, unknown>> = FilterResolver<T> | {
+    field: keyof T;
+    lookup?: FilterLookup;
+    parse?: FilterValueParser;
+} | {
+    fields: readonly (keyof T)[];
+    lookup?: FilterLookup;
+    parse?: FilterValueParser;
+};
+export interface FilterSetDefineConfig<T extends Record<string, unknown>> {
+    fields?: Partial<Record<keyof T, FieldFilterDeclaration>>;
+    aliases?: Record<string, AliasFilterDeclaration<T>>;
+    parsers?: Partial<Record<keyof T, FilterValueParser>>;
+    all?: '__all__';
+}
+/**
+ * Declarative query-param to filter translation.
+ *
+ * A `FilterSet` lets viewsets expose safe, explicit filtering behavior
+ * without leaking raw ORM filter syntax to request handlers.
+ */
 export declare class FilterSet<T extends Record<string, unknown>> {
-    private spec;
+    private readonly spec;
+    private readonly allowAllParams;
     static readonly BRAND: "tango.resources.filter_set";
     readonly __tangoBrand: typeof FilterSet.BRAND;
+    /**
+     * Resolve matching query parameters into ORM filter inputs.
+     */
+    constructor(spec: Record<string, FilterResolver<T>>, allowAllParams?: boolean);
+    /**
+     * Build a filter set from Django-style field declarations.
+     */
+    static define<T extends Record<string, unknown>>(config: FilterSetDefineConfig<T>): FilterSet<T>;
+    /**
+     * Narrow an unknown value to `FilterSet`.
+     */
     static isFilterSet<T extends Record<string, unknown>>(value: unknown): value is FilterSet<T>;
-    constructor(spec: Record<string, FilterResolver<T>>);
-    apply(params: URLSearchParams): FilterInput<T>[];
+    private static normalizeDefineConfig;
+    private static addFieldDeclaration;
+    private static isLookupArray;
+    private static normalizeAliasDeclaration;
+    private static isFilterResolverDeclaration;
+    private static createMultiFieldResolver;
+    private static createLookupResolver;
+    private static resolveLookupFilter;
+    private static resolveLookupParam;
+    private static resolveParserValue;
+    private static toScalarString;
+    /**
+     * Apply all configured resolvers against query params.
+     */
+    apply(params: TangoQueryParams): FilterInput<T>[];
+    private buildAllResolver;
     private resolveFilter;
 }

package/dist/filters/index.d.ts

@@ -3,5 +3,5 @@
  */
 export type { FilterType } from './FilterType';
 export type { RangeOperator } from './RangeOperator';
-export type { FilterResolver } from './FilterSet';
+export type { AliasFilterDeclaration, FieldFilterDeclaration, FilterLookup, FilterResolver, FilterSetDefineConfig, FilterValueParser, } from './FilterSet';
 export { FilterSet } from './FilterSet';

package/dist/index.d.ts

@@ -6,12 +6,18 @@ export * as context from './context/index';
 export * as filters from './filters/index';
 export * as pagination from './pagination/index';
 export * as paginators from './paginators/index';
+export * as resource from './resource/index';
+export * as serializer from './serializer/index';
 export * as viewset from './viewset/index';
-export * as domain from './domain/index';
+export * as view from './view/index';
 export { RequestContext } from './context/index';
 export type { BaseUser } from './context/index';
-export { FilterSet, type FilterResolver } from './filters/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, PaginationInput, type Page, type PaginatedResponse, type Paginator, } from './pagination/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 { ModelViewSet } from './viewset/index';
-export type { ModelViewSetConfig } 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';
+export type { APIViewMethod, GenericAPIViewConfig, GenericAPIViewOpenAPIDescription } from './view/index';
+export type { ResourceModelFieldMetadata, ResourceModelLike, ResourceModelMetadata } from './resource/index';