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

package/README.md

@@ -0,0 +1,40 @@
+# @zenstackhq/server
+
+Automatic CRUD API handlers and server adapters for ZenStack. Exposes your ZenStack ORM as RESTful or RPC-style API endpoints with built-in OpenAPI spec generation.
+
+## Supported Frameworks
+
+- **Express**
+- **Fastify**
+- **Next.js**
+- **Nuxt**
+- **SvelteKit**
+- **Hono**
+- **Elysia**
+- **TanStack Start**
+
+## API Styles
+
+- **REST** — Resource-oriented endpoints with [JSON:API](https://jsonapi.org/) support
+- **RPC** — Procedure-call style endpoints
+
+## Installation
+
+```bash
+npm install @zenstackhq/server
+```
+
+## Usage (Express example)
+
+```typescript
+import express from 'express';
+import { ZenStackMiddleware } from '@zenstackhq/server/express';
+import { RPCApiHandler } from '@zenstackhq/server/api';
+
+const app = express();
+app.use('/api/model', ZenStackMiddleware({...}));
+```
+
+## Learn More
+
+- [ZenStack Documentation](https://zenstack.dev/docs)

package/dist/api.cjs

@@ -1819,6 +1819,7 @@ var RestApiHandler = class {
   modelNameMapping;
   reverseModelNameMapping;
   externalIdMapping;
+  nestedRoutes;
   constructor(options) {
     this.options = options;
     this.validateOptions(options);
@@ -1838,6 +1839,7 @@ var RestApiHandler = class {
       (0, import_common_helpers3.lowerCaseFirst)(k),
       v
     ]));
+    this.nestedRoutes = options.nestedRoutes ?? false;
     this.urlPatternMap = this.buildUrlPatternMap(segmentCharset);
     this.buildTypeMap();
     this.buildSerializers();
@@ -1855,7 +1857,8 @@ var RestApiHandler = class {
       urlSegmentCharset: import_zod2.default.string().min(1).optional(),
       modelNameMapping: import_zod2.default.record(import_zod2.default.string(), import_zod2.default.string()).optional(),
       externalIdMapping: import_zod2.default.record(import_zod2.default.string(), import_zod2.default.string()).optional(),
-      queryOptions: queryOptionsSchema.optional()
+      queryOptions: queryOptionsSchema.optional(),
+      nestedRoutes: import_zod2.default.boolean().optional()
     });
     const parseResult = schema.safeParse(options);
     if (!parseResult.success) {
@@ -1880,6 +1883,12 @@ var RestApiHandler = class {
         ":type",
         ":id"
       ]), options),
+      ["nestedSingle"]: new import_url_pattern.default(buildPath([
+        ":type",
+        ":id",
+        ":relationship",
+        ":childId"
+      ]), options),
       ["fetchRelationship"]: new import_url_pattern.default(buildPath([
         ":type",
         ":id",
@@ -1899,6 +1908,81 @@ var RestApiHandler = class {
   mapModelName(modelName) {
     return this.modelNameMapping[modelName] ?? modelName;
   }
+  /**
+   * Resolves child model type and reverse relation from a parent relation name.
+   * e.g. given parentType='user', parentRelation='posts', returns { childType:'post', reverseRelation:'author' }
+   */
+  resolveNestedRelation(parentType, parentRelation) {
+    const parentInfo = this.getModelInfo(parentType);
+    if (!parentInfo) return void 0;
+    const field = this.schema.models[parentInfo.name]?.fields[parentRelation];
+    if (!field?.relation) return void 0;
+    const reverseRelation = field.relation.opposite;
+    if (!reverseRelation) return void 0;
+    return {
+      childType: (0, import_common_helpers3.lowerCaseFirst)(field.type),
+      reverseRelation,
+      isCollection: !!field.array
+    };
+  }
+  mergeFilters(left, right) {
+    if (!left) {
+      return right;
+    }
+    if (!right) {
+      return left;
+    }
+    return {
+      AND: [
+        left,
+        right
+      ]
+    };
+  }
+  /**
+   * 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')
+   */
+  buildNestedParentFilter(parentType, parentId, parentRelation) {
+    const parentInfo = this.getModelInfo(parentType);
+    if (!parentInfo) {
+      return {
+        filter: void 0,
+        error: this.makeUnsupportedModelError(parentType)
+      };
+    }
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return {
+        filter: void 0,
+        error: this.makeError("invalidPath", `invalid nested route: cannot resolve relation "${parentType}.${parentRelation}"`)
+      };
+    }
+    const { reverseRelation } = resolved;
+    const childInfo = this.getModelInfo(resolved.childType);
+    if (!childInfo) {
+      return {
+        filter: void 0,
+        error: this.makeUnsupportedModelError(resolved.childType)
+      };
+    }
+    const reverseRelInfo = childInfo.relationships[reverseRelation];
+    const relationFilter = reverseRelInfo?.isCollection ? {
+      [reverseRelation]: {
+        some: this.makeIdFilter(parentInfo.idFields, parentId, false)
+      }
+    } : {
+      [reverseRelation]: {
+        is: this.makeIdFilter(parentInfo.idFields, parentId, false)
+      }
+    };
+    return {
+      filter: relationFilter,
+      error: void 0
+    };
+  }
   matchUrlPattern(path, routeType) {
     const pattern = this.urlPatternMap[routeType];
     if (!pattern) {
@@ -1946,6 +2030,10 @@ var RestApiHandler = class {
           if (match4) {
             return await this.processReadRelationship(client, match4.type, match4.id, match4.relationship, query);
           }
+          match4 = this.matchUrlPattern(path, "nestedSingle");
+          if (match4 && this.nestedRoutes && this.resolveNestedRelation(match4.type, match4.relationship)?.isCollection) {
+            return await this.processNestedSingleRead(client, match4.type, match4.id, match4.relationship, match4.childId, query);
+          }
           match4 = this.matchUrlPattern(path, "collection");
           if (match4) {
             return await this.processCollectionRead(client, match4.type, query);
@@ -1956,6 +2044,10 @@ var RestApiHandler = class {
           if (!requestBody) {
             return this.makeError("invalidPayload");
           }
+          const nestedMatch = this.matchUrlPattern(path, "fetchRelationship");
+          if (nestedMatch && this.nestedRoutes && this.resolveNestedRelation(nestedMatch.type, nestedMatch.relationship)?.isCollection) {
+            return await this.processNestedCreate(client, nestedMatch.type, nestedMatch.id, nestedMatch.relationship, query, requestBody);
+          }
           let match4 = this.matchUrlPattern(path, "collection");
           if (match4) {
             const body = requestBody;
@@ -1978,24 +2070,36 @@ var RestApiHandler = class {
           if (!requestBody) {
             return this.makeError("invalidPayload");
           }
-          let match4 = this.matchUrlPattern(path, "single");
+          let match4 = this.matchUrlPattern(path, "relationship");
           if (match4) {
-            return await this.processUpdate(client, match4.type, match4.id, query, requestBody);
+            return await this.processRelationshipCRUD(client, "update", match4.type, match4.id, match4.relationship, query, requestBody);
           }
-          match4 = this.matchUrlPattern(path, "relationship");
+          const nestedToOnePatchMatch = this.matchUrlPattern(path, "fetchRelationship");
+          if (nestedToOnePatchMatch && this.nestedRoutes && this.resolveNestedRelation(nestedToOnePatchMatch.type, nestedToOnePatchMatch.relationship) && !this.resolveNestedRelation(nestedToOnePatchMatch.type, nestedToOnePatchMatch.relationship)?.isCollection) {
+            return await this.processNestedUpdate(client, nestedToOnePatchMatch.type, nestedToOnePatchMatch.id, nestedToOnePatchMatch.relationship, void 0, query, requestBody);
+          }
+          const nestedPatchMatch = this.matchUrlPattern(path, "nestedSingle");
+          if (nestedPatchMatch && this.nestedRoutes && this.resolveNestedRelation(nestedPatchMatch.type, nestedPatchMatch.relationship)?.isCollection) {
+            return await this.processNestedUpdate(client, nestedPatchMatch.type, nestedPatchMatch.id, nestedPatchMatch.relationship, nestedPatchMatch.childId, query, requestBody);
+          }
+          match4 = this.matchUrlPattern(path, "single");
           if (match4) {
-            return await this.processRelationshipCRUD(client, "update", match4.type, match4.id, match4.relationship, query, requestBody);
+            return await this.processUpdate(client, match4.type, match4.id, query, requestBody);
           }
           return this.makeError("invalidPath");
         }
         case "DELETE": {
-          let match4 = this.matchUrlPattern(path, "single");
+          let match4 = this.matchUrlPattern(path, "relationship");
           if (match4) {
-            return await this.processDelete(client, match4.type, match4.id);
+            return await this.processRelationshipCRUD(client, "delete", match4.type, match4.id, match4.relationship, query, requestBody);
           }
-          match4 = this.matchUrlPattern(path, "relationship");
+          const nestedDeleteMatch = this.matchUrlPattern(path, "nestedSingle");
+          if (nestedDeleteMatch && this.nestedRoutes && this.resolveNestedRelation(nestedDeleteMatch.type, nestedDeleteMatch.relationship)?.isCollection) {
+            return await this.processNestedDelete(client, nestedDeleteMatch.type, nestedDeleteMatch.id, nestedDeleteMatch.relationship, nestedDeleteMatch.childId);
+          }
+          match4 = this.matchUrlPattern(path, "single");
           if (match4) {
-            return await this.processRelationshipCRUD(client, "delete", match4.type, match4.id, match4.relationship, query, requestBody);
+            return await this.processDelete(client, match4.type, match4.id);
           }
           return this.makeError("invalidPath");
         }
@@ -2082,20 +2186,23 @@ var RestApiHandler = class {
     log(this.log, "debug", () => `sending error response: ${(0, import_common_helpers3.safeJSONStringify)(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
     return resp;
   }
-  async processSingleRead(client, type, resourceId, query) {
-    const typeInfo = this.getModelInfo(type);
-    if (!typeInfo) {
-      return this.makeUnsupportedModelError(type);
-    }
-    const args = {
-      where: this.makeIdFilter(typeInfo.idFields, resourceId)
-    };
+  /**
+   * 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.
+   */
+  buildSingleReadArgs(type, query) {
+    const args = {};
     this.includeRelationshipIds(type, args, "include");
     let include;
     if (query?.["include"]) {
       const { select: select2, error: error2, allIncludes } = this.buildRelationSelect(type, query["include"], query);
       if (error2) {
-        return error2;
+        return {
+          args,
+          include,
+          error: error2
+        };
       }
       if (select2) {
         args.include = {
@@ -2106,7 +2213,11 @@ var RestApiHandler = class {
       include = allIncludes;
     }
     const { select, error } = this.buildPartialSelect(type, query);
-    if (error) return error;
+    if (error) return {
+      args,
+      include,
+      error
+    };
     if (select) {
       args.select = {
         ...select,
@@ -2120,6 +2231,19 @@ var RestApiHandler = class {
         args.include = void 0;
       }
     }
+    return {
+      args,
+      include
+    };
+  }
+  async processSingleRead(client, type, resourceId, query) {
+    const typeInfo = this.getModelInfo(type);
+    if (!typeInfo) {
+      return this.makeUnsupportedModelError(type);
+    }
+    const { args, include, error } = this.buildSingleReadArgs(type, query);
+    if (error) return error;
+    args.where = this.makeIdFilter(typeInfo.idFields, resourceId);
     const entity = await client[type].findUnique(args);
     if (entity) {
       return {
@@ -2304,8 +2428,12 @@ var RestApiHandler = class {
     }
     if (limit === Infinity) {
       const entities = await client[type].findMany(args);
+      const mappedType = this.mapModelName(type);
       const body = await this.serializeItems(type, entities, {
-        include
+        include,
+        linkers: {
+          document: new import_ts_japi.default.Linker(() => this.makeLinkUrl(`/${mappedType}`))
+        }
       });
       const total = entities.length;
       body.meta = this.addTotalCountToMeta(body.meta, total);
@@ -2327,6 +2455,7 @@ var RestApiHandler = class {
       const options = {
         include,
         linkers: {
+          document: new import_ts_japi.default.Linker(() => this.makeLinkUrl(`/${mappedType}`)),
           paginator: this.makePaginator(url, offset, limit, total)
         }
       };
@@ -2338,6 +2467,278 @@ var RestApiHandler = class {
       };
     }
   }
+  /**
+   * 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.
+   */
+  makeNestedLinkUrl(parentType, parentId, parentRelation, childId) {
+    const mappedParentType = this.mapModelName(parentType);
+    const base = `/${mappedParentType}/${parentId}/${parentRelation}`;
+    return childId ? `${base}/${childId}` : base;
+  }
+  async processNestedSingleRead(client, parentType, parentId, parentRelation, childId, query) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const { filter: nestedFilter, error: nestedError } = this.buildNestedParentFilter(parentType, parentId, parentRelation);
+    if (nestedError) return nestedError;
+    const childType = resolved.childType;
+    const typeInfo = this.getModelInfo(childType);
+    const { args, include, error } = this.buildSingleReadArgs(childType, query);
+    if (error) return error;
+    args.where = this.mergeFilters(this.makeIdFilter(typeInfo.idFields, childId), nestedFilter);
+    const entity = await client[childType].findFirst(args);
+    if (!entity) return this.makeError("notFound");
+    const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation, childId));
+    const nestedLinker = new import_ts_japi.default.Linker(() => linkUrl);
+    return {
+      status: 200,
+      body: await this.serializeItems(childType, entity, {
+        include,
+        linkers: {
+          document: nestedLinker,
+          resource: nestedLinker
+        }
+      })
+    };
+  }
+  async processNestedCreate(client, parentType, parentId, parentRelation, _query, requestBody) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const childType = resolved.childType;
+    const childInfo = this.getModelInfo(childType);
+    const { attributes, relationships, error } = this.processRequestBody(requestBody);
+    if (error) return error;
+    const createData = {
+      ...attributes
+    };
+    if (relationships) {
+      for (const [key, data] of Object.entries(relationships)) {
+        if (!data?.data) {
+          return this.makeError("invalidRelationData");
+        }
+        if (key === resolved.reverseRelation) {
+          return this.makeError("invalidPayload", `Relation "${key}" is controlled by the parent route and cannot be set in the request payload`);
+        }
+        const relationInfo = childInfo.relationships[key];
+        if (!relationInfo) {
+          return this.makeUnsupportedRelationshipError(childType, key, 400);
+        }
+        if (relationInfo.isCollection) {
+          createData[key] = {
+            connect: (0, import_common_helpers3.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
+          };
+        } else {
+          if (typeof data.data !== "object") {
+            return this.makeError("invalidRelationData");
+          }
+          createData[key] = {
+            connect: this.makeIdConnect(relationInfo.idFields, data.data.id)
+          };
+        }
+      }
+    }
+    const parentFkFields = Object.values(childInfo.fields).filter((f) => f.foreignKeyFor?.includes(resolved.reverseRelation));
+    if (parentFkFields.some((f) => Object.prototype.hasOwnProperty.call(createData, f.name))) {
+      return this.makeError("invalidPayload", `Relation "${resolved.reverseRelation}" is controlled by the parent route and cannot be set in the request payload`);
+    }
+    await client[parentType].update({
+      where: this.makeIdFilter(parentInfo.idFields, parentId),
+      data: {
+        [parentRelation]: {
+          create: createData
+        }
+      }
+    });
+    const { filter: nestedFilter, error: filterError } = this.buildNestedParentFilter(parentType, parentId, parentRelation);
+    if (filterError) return filterError;
+    const fetchArgs = {
+      where: nestedFilter
+    };
+    this.includeRelationshipIds(childType, fetchArgs, "include");
+    if (childInfo.idFields[0]) {
+      fetchArgs.orderBy = {
+        [childInfo.idFields[0].name]: "desc"
+      };
+    }
+    const entity = await client[childType].findFirst(fetchArgs);
+    if (!entity) return this.makeError("notFound");
+    const collectionPath = this.makeNestedLinkUrl(parentType, parentId, parentRelation);
+    const resourceLinker = new import_ts_japi.default.Linker((item) => this.makeLinkUrl(`${collectionPath}/${this.getId(childInfo.name, item)}`));
+    return {
+      status: 201,
+      body: await this.serializeItems(childType, entity, {
+        linkers: {
+          document: resourceLinker,
+          resource: resourceLinker
+        }
+      })
+    };
+  }
+  /**
+   * 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 }`.
+   */
+  buildNestedUpdatePayload(childType, typeInfo, rev, requestBody) {
+    const { attributes, relationships, error } = this.processRequestBody(requestBody);
+    if (error) return {
+      error
+    };
+    const updateData = {
+      ...attributes
+    };
+    if (relationships && Object.prototype.hasOwnProperty.call(relationships, rev)) {
+      return {
+        error: this.makeError("invalidPayload", `Relation "${rev}" cannot be changed via a nested route`)
+      };
+    }
+    const fkFields = Object.values(typeInfo.fields).filter((f) => f.foreignKeyFor?.includes(rev));
+    if (fkFields.some((f) => Object.prototype.hasOwnProperty.call(updateData, f.name))) {
+      return {
+        error: this.makeError("invalidPayload", `Relation "${rev}" cannot be changed via a nested route`)
+      };
+    }
+    if (relationships) {
+      for (const [key, data] of Object.entries(relationships)) {
+        if (!data?.data) {
+          return {
+            error: this.makeError("invalidRelationData")
+          };
+        }
+        const relationInfo = typeInfo.relationships[key];
+        if (!relationInfo) {
+          return {
+            error: this.makeUnsupportedRelationshipError(childType, key, 400)
+          };
+        }
+        if (relationInfo.isCollection) {
+          updateData[key] = {
+            set: (0, import_common_helpers3.enumerate)(data.data).map((item) => ({
+              [this.makeDefaultIdKey(relationInfo.idFields)]: item.id
+            }))
+          };
+        } else {
+          if (typeof data.data !== "object") {
+            return {
+              error: this.makeError("invalidRelationData")
+            };
+          }
+          updateData[key] = {
+            connect: {
+              [this.makeDefaultIdKey(relationInfo.idFields)]: data.data.id
+            }
+          };
+        }
+      }
+    }
+    return {
+      updateData
+    };
+  }
+  /**
+   * Handles PATCH /:type/:id/:relationship/:childId (to-many) and
+   * PATCH /:type/:id/:relationship (to-one, childId undefined).
+   */
+  async processNestedUpdate(client, parentType, parentId, parentRelation, childId, _query, requestBody) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const childType = resolved.childType;
+    const typeInfo = this.getModelInfo(childType);
+    const { updateData, error } = this.buildNestedUpdatePayload(childType, typeInfo, resolved.reverseRelation, requestBody);
+    if (error) return error;
+    if (childId) {
+      await client[parentType].update({
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        data: {
+          [parentRelation]: {
+            update: {
+              where: this.makeIdFilter(typeInfo.idFields, childId),
+              data: updateData
+            }
+          }
+        }
+      });
+      const fetchArgs = {
+        where: this.makeIdFilter(typeInfo.idFields, childId)
+      };
+      this.includeRelationshipIds(childType, fetchArgs, "include");
+      const entity = await client[childType].findUnique(fetchArgs);
+      if (!entity) return this.makeError("notFound");
+      const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation, childId));
+      const nestedLinker = new import_ts_japi.default.Linker(() => linkUrl);
+      return {
+        status: 200,
+        body: await this.serializeItems(childType, entity, {
+          linkers: {
+            document: nestedLinker,
+            resource: nestedLinker
+          }
+        })
+      };
+    } else {
+      await client[parentType].update({
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        data: {
+          [parentRelation]: {
+            update: updateData
+          }
+        }
+      });
+      const childIncludeArgs = {};
+      this.includeRelationshipIds(childType, childIncludeArgs, "include");
+      const fetchArgs = {
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        select: {
+          [parentRelation]: childIncludeArgs.include ? {
+            include: childIncludeArgs.include
+          } : true
+        }
+      };
+      const parent = await client[parentType].findUnique(fetchArgs);
+      const entity = parent?.[parentRelation];
+      if (!entity) return this.makeError("notFound");
+      const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation));
+      const nestedLinker = new import_ts_japi.default.Linker(() => linkUrl);
+      return {
+        status: 200,
+        body: await this.serializeItems(childType, entity, {
+          linkers: {
+            document: nestedLinker,
+            resource: nestedLinker
+          }
+        })
+      };
+    }
+  }
+  async processNestedDelete(client, parentType, parentId, parentRelation, childId) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const typeInfo = this.getModelInfo(resolved.childType);
+    await client[parentType].update({
+      where: this.makeIdFilter(parentInfo.idFields, parentId),
+      data: {
+        [parentRelation]: {
+          delete: this.makeIdFilter(typeInfo.idFields, childId)
+        }
+      }
+    });
+    return {
+      status: 200,
+      body: {
+        meta: {}
+      }
+    };
+  }
   buildPartialSelect(type, query) {
     const selectFieldsQuery = query?.[`fields[${type}]`];
     if (!selectFieldsQuery) {