pocketbase-zod-schema 0.7.0 → 0.7.2

package/dist/schema.d.cts

@@ -255,11 +255,23 @@ interface CollectionConfig {
      * Optional collection type
      * - "base": Standard collection (default)
      * - "auth": Authentication collection with system auth fields
+     * - "view": Read-only collection backed by a SQL query (requires viewQuery)
      *
      * If not specified, the type will be auto-detected based on field presence
      * (collections with both email and password fields are detected as auth)
+     *
+     * Prefer defineView() over type: "view" - it enforces the constraints
+     * PocketBase places on view collections at compile time.
+     */
+    type?: "base" | "auth" | "view";
+    /**
+     * SQL SELECT statement backing a view collection
+     *
+     * Only valid when type is "view", where it is required. PocketBase derives
+     * the collection's fields by running this query, so the Zod schema is used
+     * for TypeScript types only.
      */
-    type?: "base" | "auth";
+    viewQuery?: string;
     /**
      * Future extensibility - additional options can be added here
      */
@@ -344,6 +356,120 @@ interface CollectionConfig {
  */
 declare function defineCollection(config: CollectionConfig): z.ZodObject<any>;
 
+/**
+ * Permission rules that apply to a view collection
+ *
+ * View collections are read-only: PocketBase rejects createRule, updateRule,
+ * deleteRule and manageRule on them, so only the two read rules are accepted.
+ */
+interface ViewPermissionSchema {
+    /** Controls who can list/query the view's rows */
+    listRule?: RuleExpression;
+    /** Controls who can view an individual row */
+    viewRule?: RuleExpression;
+}
+/**
+ * Configuration options for defining a view collection
+ */
+interface ViewCollectionConfig {
+    /**
+     * The name of the PocketBase collection
+     */
+    collectionName: string;
+    /**
+     * The Zod schema describing the shape of a row
+     *
+     * For views this is used for TypeScript type generation and application-side
+     * parsing only - PocketBase derives the collection's actual fields from the
+     * SQL query when the collection is saved.
+     */
+    schema: z.ZodObject<any>;
+    /**
+     * The SQL SELECT statement backing the view
+     *
+     * Use the `sql` tagged template for consistent formatting.
+     */
+    viewQuery: string;
+    /**
+     * Optional read permissions (listRule / viewRule)
+     */
+    permissions?: ViewPermissionSchema;
+}
+/**
+ * Removes the common leading indentation from a multi-line string and trims
+ * blank leading/trailing lines
+ *
+ * Keeps generated migrations stable when a query is re-indented in the source
+ * file, since only the relative indentation is preserved. Also used when
+ * reading a query back out of a migration file, where the generator has
+ * indented it to fit the surrounding code.
+ *
+ * @param value - Raw multi-line string
+ * @returns Dedented string
+ */
+declare function dedentSql(value: string): string;
+/**
+ * Tagged template for SQL view queries
+ *
+ * Interpolates values, strips the common leading indentation and trims blank
+ * leading/trailing lines. Returns a plain string, so a regular string literal
+ * works anywhere `sql` does.
+ *
+ * @example
+ * const query = sql`
+ *   SELECT p.id AS id, p.title AS title
+ *     FROM Projects p
+ * `;
+ * // "SELECT p.id AS id, p.title AS title\n  FROM Projects p"
+ */
+declare function sql(strings: TemplateStringsArray, ...values: Array<string | number>): string;
+/**
+ * Validates a view query, throwing with an actionable message when it can't work
+ *
+ * @param collectionName - Collection name, used in error messages
+ * @param viewQuery - The SQL query to validate
+ */
+declare function validateViewQuery(collectionName: string, viewQuery: unknown): asserts viewQuery is string;
+/**
+ * Defines a read-only PocketBase view collection backed by a SQL query
+ *
+ * PocketBase derives the collection's fields by running the query, so the Zod
+ * schema only describes the shape for TypeScript types and application-side
+ * parsing. Views cannot have indexes and only support listRule / viewRule.
+ *
+ * The generated migration creates the collection with `type: "view"` and the
+ * query; changing the SQL later produces an in-place `viewQuery` update, which
+ * keeps the collection id stable.
+ *
+ * @param config - View collection configuration
+ * @returns The schema with view metadata attached
+ *
+ * @example
+ * export default defineView({
+ *   collectionName: "ProjectStats",
+ *   schema: ProjectStatsSchema,
+ *   viewQuery: sql`
+ *     SELECT p.OwnerUser AS id,
+ *            p.OwnerUser AS OwnerUser,
+ *            COUNT(*)    AS projectCount
+ *       FROM Projects p
+ *      GROUP BY p.OwnerUser
+ *   `,
+ *   permissions: {
+ *     listRule: "OwnerUser = @request.auth.id",
+ *     viewRule: "OwnerUser = @request.auth.id",
+ *   },
+ * });
+ *
+ * @example
+ * // Requirements PocketBase places on the query:
+ * // - the outermost SELECT must expose an `id` column
+ * // - a relation column must be selected bare (e.g. `p.OwnerUser AS OwnerUser`)
+ * //   from the outer table for PocketBase to infer it as a relation field
+ * // - no top-level UNION (wrap unions in a subquery)
+ */
+declare function defineView(config: ViewCollectionConfig): z.ZodObject<any>;
+
 /**
  * Predefined permission templates for common access control patterns
  */
@@ -434,4 +560,4 @@ declare function createPermissions(permissions: Partial<PermissionSchema>): Perm
  */
 declare function mergePermissions(...schemas: Partial<PermissionSchema>[]): PermissionSchema;
 
-export { type CollectionConfig, PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, type RelationConfig, RelationField, type RelationsConfig, RelationsField, RuleExpression, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, defineCollection, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, validatePermissionConfig, validateRuleExpression, withIndexes, withPermissions };
+export { type CollectionConfig, PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, type RelationConfig, RelationField, type RelationsConfig, RelationsField, RuleExpression, type ViewCollectionConfig, type ViewPermissionSchema, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, dedentSql, defineCollection, defineView, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, sql, validatePermissionConfig, validateRuleExpression, validateViewQuery, withIndexes, withPermissions };

package/dist/schema.d.ts

@@ -255,11 +255,23 @@ interface CollectionConfig {
      * Optional collection type
      * - "base": Standard collection (default)
      * - "auth": Authentication collection with system auth fields
+     * - "view": Read-only collection backed by a SQL query (requires viewQuery)
      *
      * If not specified, the type will be auto-detected based on field presence
      * (collections with both email and password fields are detected as auth)
+     *
+     * Prefer defineView() over type: "view" - it enforces the constraints
+     * PocketBase places on view collections at compile time.
+     */
+    type?: "base" | "auth" | "view";
+    /**
+     * SQL SELECT statement backing a view collection
+     *
+     * Only valid when type is "view", where it is required. PocketBase derives
+     * the collection's fields by running this query, so the Zod schema is used
+     * for TypeScript types only.
      */
-    type?: "base" | "auth";
+    viewQuery?: string;
     /**
      * Future extensibility - additional options can be added here
      */
@@ -344,6 +356,120 @@ interface CollectionConfig {
  */
 declare function defineCollection(config: CollectionConfig): z.ZodObject<any>;
 
+/**
+ * Permission rules that apply to a view collection
+ *
+ * View collections are read-only: PocketBase rejects createRule, updateRule,
+ * deleteRule and manageRule on them, so only the two read rules are accepted.
+ */
+interface ViewPermissionSchema {
+    /** Controls who can list/query the view's rows */
+    listRule?: RuleExpression;
+    /** Controls who can view an individual row */
+    viewRule?: RuleExpression;
+}
+/**
+ * Configuration options for defining a view collection
+ */
+interface ViewCollectionConfig {
+    /**
+     * The name of the PocketBase collection
+     */
+    collectionName: string;
+    /**
+     * The Zod schema describing the shape of a row
+     *
+     * For views this is used for TypeScript type generation and application-side
+     * parsing only - PocketBase derives the collection's actual fields from the
+     * SQL query when the collection is saved.
+     */
+    schema: z.ZodObject<any>;
+    /**
+     * The SQL SELECT statement backing the view
+     *
+     * Use the `sql` tagged template for consistent formatting.
+     */
+    viewQuery: string;
+    /**
+     * Optional read permissions (listRule / viewRule)
+     */
+    permissions?: ViewPermissionSchema;
+}
+/**
+ * Removes the common leading indentation from a multi-line string and trims
+ * blank leading/trailing lines
+ *
+ * Keeps generated migrations stable when a query is re-indented in the source
+ * file, since only the relative indentation is preserved. Also used when
+ * reading a query back out of a migration file, where the generator has
+ * indented it to fit the surrounding code.
+ *
+ * @param value - Raw multi-line string
+ * @returns Dedented string
+ */
+declare function dedentSql(value: string): string;
+/**
+ * Tagged template for SQL view queries
+ *
+ * Interpolates values, strips the common leading indentation and trims blank
+ * leading/trailing lines. Returns a plain string, so a regular string literal
+ * works anywhere `sql` does.
+ *
+ * @example
+ * const query = sql`
+ *   SELECT p.id AS id, p.title AS title
+ *     FROM Projects p
+ * `;
+ * // "SELECT p.id AS id, p.title AS title\n  FROM Projects p"
+ */
+declare function sql(strings: TemplateStringsArray, ...values: Array<string | number>): string;
+/**
+ * Validates a view query, throwing with an actionable message when it can't work
+ *
+ * @param collectionName - Collection name, used in error messages
+ * @param viewQuery - The SQL query to validate
+ */
+declare function validateViewQuery(collectionName: string, viewQuery: unknown): asserts viewQuery is string;
+/**
+ * Defines a read-only PocketBase view collection backed by a SQL query
+ *
+ * PocketBase derives the collection's fields by running the query, so the Zod
+ * schema only describes the shape for TypeScript types and application-side
+ * parsing. Views cannot have indexes and only support listRule / viewRule.
+ *
+ * The generated migration creates the collection with `type: "view"` and the
+ * query; changing the SQL later produces an in-place `viewQuery` update, which
+ * keeps the collection id stable.
+ *
+ * @param config - View collection configuration
+ * @returns The schema with view metadata attached
+ *
+ * @example
+ * export default defineView({
+ *   collectionName: "ProjectStats",
+ *   schema: ProjectStatsSchema,
+ *   viewQuery: sql`
+ *     SELECT p.OwnerUser AS id,
+ *            p.OwnerUser AS OwnerUser,
+ *            COUNT(*)    AS projectCount
+ *       FROM Projects p
+ *      GROUP BY p.OwnerUser
+ *   `,
+ *   permissions: {
+ *     listRule: "OwnerUser = @request.auth.id",
+ *     viewRule: "OwnerUser = @request.auth.id",
+ *   },
+ * });
+ *
+ * @example
+ * // Requirements PocketBase places on the query:
+ * // - the outermost SELECT must expose an `id` column
+ * // - a relation column must be selected bare (e.g. `p.OwnerUser AS OwnerUser`)
+ * //   from the outer table for PocketBase to infer it as a relation field
+ * // - no top-level UNION (wrap unions in a subquery)
+ */
+declare function defineView(config: ViewCollectionConfig): z.ZodObject<any>;
+
 /**
  * Predefined permission templates for common access control patterns
  */
@@ -434,4 +560,4 @@ declare function createPermissions(permissions: Partial<PermissionSchema>): Perm
  */
 declare function mergePermissions(...schemas: Partial<PermissionSchema>[]): PermissionSchema;
 
-export { type CollectionConfig, PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, type RelationConfig, RelationField, type RelationsConfig, RelationsField, RuleExpression, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, defineCollection, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, validatePermissionConfig, validateRuleExpression, withIndexes, withPermissions };
+export { type CollectionConfig, PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, type RelationConfig, RelationField, type RelationsConfig, RelationsField, RuleExpression, type ViewCollectionConfig, type ViewPermissionSchema, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, dedentSql, defineCollection, defineView, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, sql, validatePermissionConfig, validateRuleExpression, validateViewQuery, withIndexes, withPermissions };

package/dist/schema.js

@@ -91,13 +91,16 @@ function withIndexes(schema, indexes) {
   return schema.describe(JSON.stringify(metadata));
 }
 function defineCollection(config) {
-  const { collectionName, schema, permissions, indexes, type, ...futureOptions } = config;
+  const { collectionName, schema, permissions, indexes, type, viewQuery, ...futureOptions } = config;
   const metadata = {
     collectionName
   };
   if (type) {
     metadata.type = type;
   }
+  if (viewQuery !== void 0) {
+    metadata.viewQuery = viewQuery;
+  }
   if (permissions) {
     metadata.permissions = permissions;
   }
@@ -363,6 +366,88 @@ function GeoPointField() {
   };
   return schema.describe(JSON.stringify(metadata));
 }
+function dedentSql(value) {
+  const lines = value.replace(/\r\n/g, "\n").split("\n");
+  while (lines.length > 0 && lines[0].trim() === "") {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+    lines.pop();
+  }
+  if (lines.length === 0) {
+    return "";
+  }
+  let minIndent = Infinity;
+  for (const line of lines) {
+    if (line.trim() === "") continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent < minIndent) {
+      minIndent = indent;
+    }
+  }
+  if (!Number.isFinite(minIndent) || minIndent === 0) {
+    return lines.map((line) => line.trimEnd()).join("\n");
+  }
+  return lines.map((line) => line.slice(minIndent).trimEnd()).join("\n");
+}
+function sql(strings, ...values) {
+  let result = "";
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i];
+    if (i < values.length) {
+      result += String(values[i]);
+    }
+  }
+  return dedentSql(result);
+}
+function stripLeadingComments(query) {
+  let remaining = query.trim();
+  while (remaining.length > 0) {
+    if (remaining.startsWith("--")) {
+      const newline = remaining.indexOf("\n");
+      remaining = newline === -1 ? "" : remaining.slice(newline + 1).trim();
+      continue;
+    }
+    if (remaining.startsWith("/*")) {
+      const end = remaining.indexOf("*/");
+      remaining = end === -1 ? "" : remaining.slice(end + 2).trim();
+      continue;
+    }
+    break;
+  }
+  return remaining;
+}
+function validateViewQuery(collectionName, viewQuery) {
+  if (typeof viewQuery !== "string" || viewQuery.trim() === "") {
+    throw new Error(
+      `View collection "${collectionName}" requires a non-empty viewQuery. Provide the SQL SELECT statement backing the view.`
+    );
+  }
+  const body = stripLeadingComments(viewQuery);
+  if (!/^(select|with)\b/i.test(body)) {
+    throw new Error(
+      `View collection "${collectionName}" has an invalid viewQuery: it must start with SELECT or WITH. Received: ${body.slice(0, 40)}${body.length > 40 ? "..." : ""}`
+    );
+  }
+}
+function defineView(config) {
+  const { collectionName, schema, viewQuery, permissions } = config;
+  validateViewQuery(collectionName, viewQuery);
+  return defineCollection({
+    collectionName,
+    schema,
+    type: "view",
+    viewQuery,
+    // Write rules are always locked for views - PocketBase rejects anything else
+    permissions: {
+      listRule: permissions?.listRule ?? null,
+      viewRule: permissions?.viewRule ?? null,
+      createRule: null,
+      updateRule: null,
+      deleteRule: null
+    }
+  });
+}
 
 // src/utils/permission-templates.ts
 var PermissionTemplates = {
@@ -584,6 +669,6 @@ function mergePermissions(...schemas) {
   return merged;
 }
 
-export { AutodateField, BoolField, DateField, EditorField, EmailField, FIELD_METADATA_KEY, FileField, FilesField, GeoPointField, JSONField, MultiSelectField, NumberField, PermissionTemplates, RelationField, RelationsField, SelectField, SingleSelectField, TextField, URLField, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, defineCollection, extractFieldMetadata, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, validatePermissionConfig, validateRuleExpression, withIndexes, withPermissions };
+export { AutodateField, BoolField, DateField, EditorField, EmailField, FIELD_METADATA_KEY, FileField, FilesField, GeoPointField, JSONField, MultiSelectField, NumberField, PermissionTemplates, RelationField, RelationsField, SelectField, SingleSelectField, TextField, URLField, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, createPermissions, dedentSql, defineCollection, defineView, extractFieldMetadata, extractRelationMetadata, inputImageFileSchema, isPermissionSchema, isTemplateConfig, mergePermissions, omitImageFilesSchema, resolveTemplate, sql, validatePermissionConfig, validateRuleExpression, validateViewQuery, withIndexes, withPermissions };
 //# sourceMappingURL=schema.js.map
 //# sourceMappingURL=schema.js.map