@zenstackhq/server 3.5.0-beta.3 → 3.5.0-beta.5

package/dist/api.d.cts

@@ -1,6 +1,37 @@
+import { QueryOptions } from '@zenstackhq/orm';
 import { SchemaDef } from '@zenstackhq/orm/schema';
+import * as openapi_types from 'openapi-types';
+import { OpenAPIV3_1 } from 'openapi-types';
 import { A as ApiHandler, L as LogConfig, R as RequestContext, a as Response } from './types-CU_PWKr9.cjs';
-import '@zenstackhq/orm';
+
+type CommonHandlerOptions<Schema extends SchemaDef> = {
+    /** Query options that affect the behavior of the OpenAPI provider. */
+    queryOptions?: QueryOptions<Schema>;
+};
+type OpenApiSpecOptions = {
+    /** Spec title. Defaults to 'ZenStack Generated API' */
+    title?: string;
+    /** Spec version. Defaults to '1.0.0' */
+    version?: string;
+    /** Spec description. */
+    description?: string;
+    /** Spec summary. */
+    summary?: string;
+    /**
+     * When true, assumes that the schema includes access policies, and adds
+     * 403 responses to operations that can potentially be rejected.
+     */
+    respectAccessPolicies?: boolean;
+};
+/**
+ * Interface for generating OpenAPI specifications.
+ */
+interface OpenApiSpecGenerator {
+    /**
+     * Generates an OpenAPI v3.1 specification document.
+     */
+    generateSpec(options?: OpenApiSpecOptions): Promise<OpenAPIV3_1.Document>;
+}
 
 /**
  * Options for {@link RestApiHandler}
@@ -45,11 +76,19 @@ type RestApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
      * Mapping from model names to unique field name to be used as resource's ID.
      */
     externalIdMapping?: Record<string, string>;
-};
+    /**
+     * When `true`, enables nested route handling for all to-many relations:
+     * `/:parentType/:parentId/:relationName` (collection) and
+     * `/:parentType/:parentId/:relationName/:childId` (single).
+     *
+     * Defaults to `false`.
+     */
+    nestedRoutes?: boolean;
+} & CommonHandlerOptions<Schema>;
 /**
  * RESTful-style API request handler (compliant with JSON:API)
  */
-declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements ApiHandler<Schema> {
+declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements ApiHandler<Schema>, OpenApiSpecGenerator {
     private readonly options;
     private serializers;
     private readonly errors;
@@ -64,22 +103,60 @@ declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Ap
     private modelNameMapping;
     private reverseModelNameMapping;
     private externalIdMapping;
+    private nestedRoutes;
     constructor(options: RestApiHandlerOptions<Schema>);
     private validateOptions;
     get schema(): Schema;
     get log(): LogConfig | undefined;
     private buildUrlPatternMap;
     private mapModelName;
+    /**
+     * Resolves child model type and reverse relation from a parent relation name.
+     * e.g. given parentType='user', parentRelation='posts', returns { childType:'post', reverseRelation:'author' }
+     */
+    private resolveNestedRelation;
+    private mergeFilters;
+    /**
+     * Builds a WHERE filter for the child model that constrains results to those belonging to the given parent.
+     * @param parentType  lowercased parent model name
+     * @param parentId    parent resource ID string
+     * @param parentRelation  relation field name on the parent model (e.g. 'posts')
+     */
+    private buildNestedParentFilter;
     private matchUrlPattern;
     handleRequest({ client, method, path, query, requestBody }: RequestContext<Schema>): Promise<Response>;
     private handleGenericError;
     private processProcedureRequest;
     private makeProcBadInputErrorResponse;
     private makeProcGenericErrorResponse;
+    /**
+     * Builds the ORM `args` object (include, select) shared by single-read operations.
+     * Returns the args to pass to findUnique/findFirst and the resolved `include` list for serialization,
+     * or an error response if query params are invalid.
+     */
+    private buildSingleReadArgs;
     private processSingleRead;
     private processFetchRelated;
     private processReadRelationship;
     private processCollectionRead;
+    /**
+     * Builds link URL for a nested resource using parent type, parent ID, relation name, and optional child ID.
+     * Uses the parent model name mapping for the parent segment; the relation name is used as-is.
+     */
+    private makeNestedLinkUrl;
+    private processNestedSingleRead;
+    private processNestedCreate;
+    /**
+     * Builds the ORM `data` payload for a nested update, shared by both to-many (childId present)
+     * and to-one (childId absent) variants.  Returns either `{ updateData }` or `{ error }`.
+     */
+    private buildNestedUpdatePayload;
+    /**
+     * Handles PATCH /:type/:id/:relationship/:childId (to-many) and
+     * PATCH /:type/:id/:relationship (to-one, childId undefined).
+     */
+    private processNestedUpdate;
+    private processNestedDelete;
     private buildPartialSelect;
     private addTotalCountToMeta;
     private makePaginator;
@@ -122,6 +199,7 @@ declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Ap
     private makeError;
     private makeUnsupportedModelError;
     private makeUnsupportedRelationshipError;
+    generateSpec(options?: OpenApiSpecOptions): Promise<openapi_types.OpenAPIV3_1.Document<{}>>;
 }
 
 /**
@@ -136,7 +214,7 @@ type RPCApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
      * Logging configuration
      */
     log?: LogConfig;
-};
+} & CommonHandlerOptions<Schema>;
 /**
  * RPC style API request handler that mirrors the ZenStackClient API
  */
@@ -156,4 +234,4 @@ declare class RPCApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
     private processRequestPayload;
 }
 
-export { RPCApiHandler, type RPCApiHandlerOptions, RestApiHandler, type RestApiHandlerOptions };
+export { type OpenApiSpecGenerator, type OpenApiSpecOptions, RPCApiHandler, type RPCApiHandlerOptions, RestApiHandler, type RestApiHandlerOptions };

package/dist/api.d.ts

@@ -1,6 +1,37 @@
+import { QueryOptions } from '@zenstackhq/orm';
 import { SchemaDef } from '@zenstackhq/orm/schema';
+import * as openapi_types from 'openapi-types';
+import { OpenAPIV3_1 } from 'openapi-types';
 import { A as ApiHandler, L as LogConfig, R as RequestContext, a as Response } from './types-CU_PWKr9.js';
-import '@zenstackhq/orm';
+
+type CommonHandlerOptions<Schema extends SchemaDef> = {
+    /** Query options that affect the behavior of the OpenAPI provider. */
+    queryOptions?: QueryOptions<Schema>;
+};
+type OpenApiSpecOptions = {
+    /** Spec title. Defaults to 'ZenStack Generated API' */
+    title?: string;
+    /** Spec version. Defaults to '1.0.0' */
+    version?: string;
+    /** Spec description. */
+    description?: string;
+    /** Spec summary. */
+    summary?: string;
+    /**
+     * When true, assumes that the schema includes access policies, and adds
+     * 403 responses to operations that can potentially be rejected.
+     */
+    respectAccessPolicies?: boolean;
+};
+/**
+ * Interface for generating OpenAPI specifications.
+ */
+interface OpenApiSpecGenerator {
+    /**
+     * Generates an OpenAPI v3.1 specification document.
+     */
+    generateSpec(options?: OpenApiSpecOptions): Promise<OpenAPIV3_1.Document>;
+}
 
 /**
  * Options for {@link RestApiHandler}
@@ -45,11 +76,19 @@ type RestApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
      * Mapping from model names to unique field name to be used as resource's ID.
      */
     externalIdMapping?: Record<string, string>;
-};
+    /**
+     * When `true`, enables nested route handling for all to-many relations:
+     * `/:parentType/:parentId/:relationName` (collection) and
+     * `/:parentType/:parentId/:relationName/:childId` (single).
+     *
+     * Defaults to `false`.
+     */
+    nestedRoutes?: boolean;
+} & CommonHandlerOptions<Schema>;
 /**
  * RESTful-style API request handler (compliant with JSON:API)
  */
-declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements ApiHandler<Schema> {
+declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements ApiHandler<Schema>, OpenApiSpecGenerator {
     private readonly options;
     private serializers;
     private readonly errors;
@@ -64,22 +103,60 @@ declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Ap
     private modelNameMapping;
     private reverseModelNameMapping;
     private externalIdMapping;
+    private nestedRoutes;
     constructor(options: RestApiHandlerOptions<Schema>);
     private validateOptions;
     get schema(): Schema;
     get log(): LogConfig | undefined;
     private buildUrlPatternMap;
     private mapModelName;
+    /**
+     * Resolves child model type and reverse relation from a parent relation name.
+     * e.g. given parentType='user', parentRelation='posts', returns { childType:'post', reverseRelation:'author' }
+     */
+    private resolveNestedRelation;
+    private mergeFilters;
+    /**
+     * Builds a WHERE filter for the child model that constrains results to those belonging to the given parent.
+     * @param parentType  lowercased parent model name
+     * @param parentId    parent resource ID string
+     * @param parentRelation  relation field name on the parent model (e.g. 'posts')
+     */
+    private buildNestedParentFilter;
     private matchUrlPattern;
     handleRequest({ client, method, path, query, requestBody }: RequestContext<Schema>): Promise<Response>;
     private handleGenericError;
     private processProcedureRequest;
     private makeProcBadInputErrorResponse;
     private makeProcGenericErrorResponse;
+    /**
+     * Builds the ORM `args` object (include, select) shared by single-read operations.
+     * Returns the args to pass to findUnique/findFirst and the resolved `include` list for serialization,
+     * or an error response if query params are invalid.
+     */
+    private buildSingleReadArgs;
     private processSingleRead;
     private processFetchRelated;
     private processReadRelationship;
     private processCollectionRead;
+    /**
+     * Builds link URL for a nested resource using parent type, parent ID, relation name, and optional child ID.
+     * Uses the parent model name mapping for the parent segment; the relation name is used as-is.
+     */
+    private makeNestedLinkUrl;
+    private processNestedSingleRead;
+    private processNestedCreate;
+    /**
+     * Builds the ORM `data` payload for a nested update, shared by both to-many (childId present)
+     * and to-one (childId absent) variants.  Returns either `{ updateData }` or `{ error }`.
+     */
+    private buildNestedUpdatePayload;
+    /**
+     * Handles PATCH /:type/:id/:relationship/:childId (to-many) and
+     * PATCH /:type/:id/:relationship (to-one, childId undefined).
+     */
+    private processNestedUpdate;
+    private processNestedDelete;
     private buildPartialSelect;
     private addTotalCountToMeta;
     private makePaginator;
@@ -122,6 +199,7 @@ declare class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Ap
     private makeError;
     private makeUnsupportedModelError;
     private makeUnsupportedRelationshipError;
+    generateSpec(options?: OpenApiSpecOptions): Promise<openapi_types.OpenAPIV3_1.Document<{}>>;
 }
 
 /**
@@ -136,7 +214,7 @@ type RPCApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
      * Logging configuration
      */
     log?: LogConfig;
-};
+} & CommonHandlerOptions<Schema>;
 /**
  * RPC style API request handler that mirrors the ZenStackClient API
  */
@@ -156,4 +234,4 @@ declare class RPCApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
     private processRequestPayload;
 }
 
-export { RPCApiHandler, type RPCApiHandlerOptions, RestApiHandler, type RestApiHandlerOptions };
+export { type OpenApiSpecGenerator, type OpenApiSpecOptions, RPCApiHandler, type RPCApiHandlerOptions, RestApiHandler, type RestApiHandlerOptions };