pocketbase-zod-schema 0.1.2

package/dist/schema.d.cts

@@ -0,0 +1,316 @@
+import { z } from 'zod';
+import { b as PermissionTemplateConfig, P as PermissionSchema, R as RuleExpression } from './permissions-ZHafVSIx.cjs';
+export { A as APIRuleType, a as PermissionTemplate } from './permissions-ZHafVSIx.cjs';
+export { P as ProjectInputSchema, a as ProjectSchema, U as UserInputSchema, b as UserSchema } from './user-jS1aYoeD.cjs';
+
+/**
+ * Base schema fields that PocketBase automatically adds to all records
+ * These fields are managed by PocketBase and should not be set manually
+ */
+declare const baseSchema: {
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Extended base schema with timestamp fields
+ * Includes created and updated autodate fields
+ */
+declare const baseSchemaWithTimestamps: {
+    created: z.ZodString;
+    updated: z.ZodString;
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Base schema for image file collections
+ * Extends base schema with thumbnail URL and image files array
+ */
+declare const baseImageFileSchema: {
+    thumbnailURL: z.ZodOptional<z.ZodString>;
+    imageFiles: z.ZodArray<z.ZodString, "many">;
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Input schema for image file uploads
+ * Used in forms where users upload File objects
+ * Requires Node.js 20+ or browser environment with File API
+ */
+declare const inputImageFileSchema: {
+    imageFiles: z.ZodArray<z.ZodType<File, z.ZodTypeDef, File>, "many">;
+};
+/**
+ * Helper constant for omitting image files from schemas
+ * Used with Zod's .omit() method
+ */
+declare const omitImageFilesSchema: {
+    readonly imageFiles: true;
+};
+/**
+ * Creates a text field schema with optional constraints
+ * @param options - Optional constraints for the text field
+ */
+declare function textField(options?: {
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+}): z.ZodString;
+/**
+ * Creates an email field schema
+ * Maps to PocketBase 'email' field type
+ */
+declare function emailField(): z.ZodString;
+/**
+ * Creates a URL field schema
+ * Maps to PocketBase 'url' field type
+ */
+declare function urlField(): z.ZodString;
+/**
+ * Creates a number field schema with optional constraints
+ * @param options - Optional constraints for the number field
+ */
+declare function numberField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodNumber;
+/**
+ * Creates a boolean field schema
+ * Maps to PocketBase 'bool' field type
+ */
+declare function boolField(): z.ZodBoolean;
+/**
+ * Creates a date field schema
+ * Maps to PocketBase 'date' field type
+ */
+declare function dateField(): z.ZodDate;
+/**
+ * Creates a select field schema from enum values
+ * Maps to PocketBase 'select' field type
+ * @param values - Array of allowed string values
+ */
+declare function selectField<T extends [string, ...string[]]>(values: T): z.ZodEnum<z.Writeable<T>>;
+/**
+ * Creates a JSON field schema
+ * Maps to PocketBase 'json' field type
+ * @param schema - Optional Zod schema for the JSON structure
+ */
+declare function jsonField<T extends z.ZodTypeAny>(schema?: T): z.ZodRecord<z.ZodString, z.ZodAny> | T;
+/**
+ * Creates a single file field schema for form input
+ * Maps to PocketBase 'file' field type with maxSelect=1
+ * Requires Node.js 20+ or browser environment with File API
+ */
+declare function fileField(): z.ZodType<File, z.ZodTypeDef, File>;
+/**
+ * Creates a multiple file field schema for form input
+ * Maps to PocketBase 'file' field type with maxSelect>1
+ * Requires Node.js 20+ or browser environment with File API
+ * @param options - Optional constraints for the file field
+ */
+declare function filesField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodArray<z.ZodType<File, z.ZodTypeDef, File>, "many">;
+/**
+ * Creates a single relation field schema
+ * Maps to PocketBase 'relation' field type with maxSelect=1
+ * Field name should start with uppercase to be detected as relation
+ */
+declare function relationField(): z.ZodString;
+/**
+ * Creates a multiple relation field schema
+ * Maps to PocketBase 'relation' field type with maxSelect>1
+ * Field name should contain uppercase to be detected as relation
+ * @param options - Optional constraints for the relation field
+ */
+declare function relationsField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodArray<z.ZodString, "many">;
+/**
+ * Creates an editor field schema (rich text)
+ * Maps to PocketBase 'editor' field type
+ */
+declare function editorField(): z.ZodString;
+/**
+ * Creates a geo point field schema
+ * Maps to PocketBase 'geoPoint' field type
+ */
+declare function geoPointField(): z.ZodObject<{
+    lon: z.ZodNumber;
+    lat: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    lon: number;
+    lat: number;
+}, {
+    lon: number;
+    lat: number;
+}>;
+/**
+ * Attach permission metadata to a Zod schema
+ *
+ * This helper function allows you to define PocketBase API rules alongside your
+ * entity schema definitions. The permissions are stored as metadata using Zod's
+ * describe() method and will be extracted during migration generation.
+ *
+ * @param schema - The Zod schema to attach permissions to
+ * @param config - Either a PermissionTemplateConfig (for template-based permissions)
+ *                 or a PermissionSchema (for custom permissions)
+ * @returns The schema with permission metadata attached
+ *
+ * @example
+ * // Using a template
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string(), User: z.string() }),
+ *   { template: 'owner-only', ownerField: 'User' }
+ * );
+ *
+ * @example
+ * // Using custom rules
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string() }),
+ *   { listRule: '@request.auth.id != ""', viewRule: '' }
+ * );
+ *
+ * @example
+ * // Using template with custom rule overrides
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string(), User: z.string() }),
+ *   {
+ *     template: 'owner-only',
+ *     ownerField: 'User',
+ *     customRules: { listRule: '@request.auth.id != ""' }
+ *   }
+ * );
+ */
+declare function withPermissions<T extends z.ZodTypeAny>(schema: T, config: PermissionTemplateConfig | PermissionSchema): T;
+/**
+ * Attach index definitions to a Zod schema
+ *
+ * This helper function allows you to define PocketBase indexes alongside your
+ * entity schema definitions. The indexes are stored as metadata using Zod's
+ * describe() method and will be extracted during migration generation.
+ *
+ * @param schema - The Zod schema to attach indexes to
+ * @param indexes - Array of PocketBase index SQL statements
+ * @returns The schema with index metadata attached
+ *
+ * @example
+ * // Define indexes for a user schema
+ * const UserSchema = withIndexes(
+ *   withPermissions(
+ *     z.object({ name: z.string(), email: z.string().email() }),
+ *     userPermissions
+ *   ),
+ *   [
+ *     'CREATE UNIQUE INDEX idx_users_email ON users (email)',
+ *     'CREATE INDEX idx_users_name ON users (name)'
+ *   ]
+ * );
+ *
+ * @example
+ * // Single index
+ * const ProjectSchema = withIndexes(
+ *   ProjectDatabaseSchema,
+ *   ['CREATE INDEX idx_projects_status ON projects (status)']
+ * );
+ */
+declare function withIndexes<T extends z.ZodTypeAny>(schema: T, indexes: string[]): T;
+
+/**
+ * Predefined permission templates for common access control patterns
+ */
+declare const PermissionTemplates: {
+    /**
+     * Public access - anyone can perform all operations
+     */
+    public: () => PermissionSchema;
+    /**
+     * Authenticated users only - requires valid authentication for all operations
+     */
+    authenticated: () => PermissionSchema;
+    /**
+     * Owner-only access - users can only manage their own records
+     * @param ownerField - Name of the relation field pointing to user (default: 'User')
+     */
+    ownerOnly: (ownerField?: string) => PermissionSchema;
+    /**
+     * Admin/superuser only access
+     * Assumes a 'role' field exists with 'admin' value
+     * @param roleField - Name of the role field (default: 'role')
+     */
+    adminOnly: (roleField?: string) => PermissionSchema;
+    /**
+     * Public read, authenticated write
+     * Anyone can list/view, but only authenticated users can create/update/delete
+     */
+    readPublic: () => PermissionSchema;
+    /**
+     * Locked access - only superusers can perform operations
+     * All rules are set to null (locked)
+     */
+    locked: () => PermissionSchema;
+    /**
+     * Read-only authenticated - authenticated users can read, no write access
+     */
+    readOnlyAuthenticated: () => PermissionSchema;
+};
+/**
+ * Resolve template configuration to concrete permission schema
+ * @param config - Template configuration or direct permission schema
+ * @returns Resolved permission schema with all rules defined
+ */
+declare function resolveTemplate(config: PermissionTemplateConfig): PermissionSchema;
+/**
+ * Check if a configuration is a template config or direct permission schema
+ * @param config - Configuration to check
+ * @returns True if it's a template configuration
+ */
+declare function isTemplateConfig(config: PermissionTemplateConfig | PermissionSchema): config is PermissionTemplateConfig;
+/**
+ * Check if a configuration is a direct permission schema
+ * @param config - Configuration to check
+ * @returns True if it's a direct permission schema
+ */
+declare function isPermissionSchema(config: PermissionTemplateConfig | PermissionSchema): config is PermissionSchema;
+/**
+ * Validation result for permission configuration
+ */
+interface PermissionValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a permission configuration
+ * @param config - Permission configuration to validate
+ * @param isAuthCollection - Whether this is for an auth collection
+ * @returns Validation result
+ */
+declare function validatePermissionConfig(config: PermissionTemplateConfig | PermissionSchema, isAuthCollection?: boolean): PermissionValidationResult;
+/**
+ * Validate a single rule expression for basic syntax
+ * @param expression - Rule expression to validate
+ * @returns Validation result
+ */
+declare function validateRuleExpression(expression: RuleExpression): PermissionValidationResult;
+/**
+ * Create a custom permission schema with type safety
+ * @param permissions - Partial permission schema
+ * @returns Complete permission schema with null defaults
+ */
+declare function createPermissions(permissions: Partial<PermissionSchema>): PermissionSchema;
+/**
+ * Merge multiple permission schemas, with later schemas taking precedence
+ * @param schemas - Permission schemas to merge
+ * @returns Merged permission schema
+ */
+declare function mergePermissions(...schemas: Partial<PermissionSchema>[]): PermissionSchema;
+
+export { PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, RuleExpression, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, boolField, createPermissions, dateField, editorField, emailField, fileField, filesField, geoPointField, inputImageFileSchema, isPermissionSchema, isTemplateConfig, jsonField, mergePermissions, numberField, omitImageFilesSchema, relationField, relationsField, resolveTemplate, selectField, textField, urlField, validatePermissionConfig, validateRuleExpression, withIndexes, withPermissions };

package/dist/schema.d.ts

@@ -0,0 +1,316 @@
+import { z } from 'zod';
+import { b as PermissionTemplateConfig, P as PermissionSchema, R as RuleExpression } from './permissions-ZHafVSIx.js';
+export { A as APIRuleType, a as PermissionTemplate } from './permissions-ZHafVSIx.js';
+export { P as ProjectInputSchema, a as ProjectSchema, U as UserInputSchema, b as UserSchema } from './user-jS1aYoeD.js';
+
+/**
+ * Base schema fields that PocketBase automatically adds to all records
+ * These fields are managed by PocketBase and should not be set manually
+ */
+declare const baseSchema: {
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Extended base schema with timestamp fields
+ * Includes created and updated autodate fields
+ */
+declare const baseSchemaWithTimestamps: {
+    created: z.ZodString;
+    updated: z.ZodString;
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Base schema for image file collections
+ * Extends base schema with thumbnail URL and image files array
+ */
+declare const baseImageFileSchema: {
+    thumbnailURL: z.ZodOptional<z.ZodString>;
+    imageFiles: z.ZodArray<z.ZodString, "many">;
+    id: z.ZodString;
+    collectionId: z.ZodString;
+    collectionName: z.ZodString;
+    expand: z.ZodRecord<z.ZodString, z.ZodAny>;
+};
+/**
+ * Input schema for image file uploads
+ * Used in forms where users upload File objects
+ * Requires Node.js 20+ or browser environment with File API
+ */
+declare const inputImageFileSchema: {
+    imageFiles: z.ZodArray<z.ZodType<File, z.ZodTypeDef, File>, "many">;
+};
+/**
+ * Helper constant for omitting image files from schemas
+ * Used with Zod's .omit() method
+ */
+declare const omitImageFilesSchema: {
+    readonly imageFiles: true;
+};
+/**
+ * Creates a text field schema with optional constraints
+ * @param options - Optional constraints for the text field
+ */
+declare function textField(options?: {
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+}): z.ZodString;
+/**
+ * Creates an email field schema
+ * Maps to PocketBase 'email' field type
+ */
+declare function emailField(): z.ZodString;
+/**
+ * Creates a URL field schema
+ * Maps to PocketBase 'url' field type
+ */
+declare function urlField(): z.ZodString;
+/**
+ * Creates a number field schema with optional constraints
+ * @param options - Optional constraints for the number field
+ */
+declare function numberField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodNumber;
+/**
+ * Creates a boolean field schema
+ * Maps to PocketBase 'bool' field type
+ */
+declare function boolField(): z.ZodBoolean;
+/**
+ * Creates a date field schema
+ * Maps to PocketBase 'date' field type
+ */
+declare function dateField(): z.ZodDate;
+/**
+ * Creates a select field schema from enum values
+ * Maps to PocketBase 'select' field type
+ * @param values - Array of allowed string values
+ */
+declare function selectField<T extends [string, ...string[]]>(values: T): z.ZodEnum<z.Writeable<T>>;
+/**
+ * Creates a JSON field schema
+ * Maps to PocketBase 'json' field type
+ * @param schema - Optional Zod schema for the JSON structure
+ */
+declare function jsonField<T extends z.ZodTypeAny>(schema?: T): z.ZodRecord<z.ZodString, z.ZodAny> | T;
+/**
+ * Creates a single file field schema for form input
+ * Maps to PocketBase 'file' field type with maxSelect=1
+ * Requires Node.js 20+ or browser environment with File API
+ */
+declare function fileField(): z.ZodType<File, z.ZodTypeDef, File>;
+/**
+ * Creates a multiple file field schema for form input
+ * Maps to PocketBase 'file' field type with maxSelect>1
+ * Requires Node.js 20+ or browser environment with File API
+ * @param options - Optional constraints for the file field
+ */
+declare function filesField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodArray<z.ZodType<File, z.ZodTypeDef, File>, "many">;
+/**
+ * Creates a single relation field schema
+ * Maps to PocketBase 'relation' field type with maxSelect=1
+ * Field name should start with uppercase to be detected as relation
+ */
+declare function relationField(): z.ZodString;
+/**
+ * Creates a multiple relation field schema
+ * Maps to PocketBase 'relation' field type with maxSelect>1
+ * Field name should contain uppercase to be detected as relation
+ * @param options - Optional constraints for the relation field
+ */
+declare function relationsField(options?: {
+    min?: number;
+    max?: number;
+}): z.ZodArray<z.ZodString, "many">;
+/**
+ * Creates an editor field schema (rich text)
+ * Maps to PocketBase 'editor' field type
+ */
+declare function editorField(): z.ZodString;
+/**
+ * Creates a geo point field schema
+ * Maps to PocketBase 'geoPoint' field type
+ */
+declare function geoPointField(): z.ZodObject<{
+    lon: z.ZodNumber;
+    lat: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    lon: number;
+    lat: number;
+}, {
+    lon: number;
+    lat: number;
+}>;
+/**
+ * Attach permission metadata to a Zod schema
+ *
+ * This helper function allows you to define PocketBase API rules alongside your
+ * entity schema definitions. The permissions are stored as metadata using Zod's
+ * describe() method and will be extracted during migration generation.
+ *
+ * @param schema - The Zod schema to attach permissions to
+ * @param config - Either a PermissionTemplateConfig (for template-based permissions)
+ *                 or a PermissionSchema (for custom permissions)
+ * @returns The schema with permission metadata attached
+ *
+ * @example
+ * // Using a template
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string(), User: z.string() }),
+ *   { template: 'owner-only', ownerField: 'User' }
+ * );
+ *
+ * @example
+ * // Using custom rules
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string() }),
+ *   { listRule: '@request.auth.id != ""', viewRule: '' }
+ * );
+ *
+ * @example
+ * // Using template with custom rule overrides
+ * const ProjectSchema = withPermissions(
+ *   z.object({ title: z.string(), User: z.string() }),
+ *   {
+ *     template: 'owner-only',
+ *     ownerField: 'User',
+ *     customRules: { listRule: '@request.auth.id != ""' }
+ *   }
+ * );
+ */
+declare function withPermissions<T extends z.ZodTypeAny>(schema: T, config: PermissionTemplateConfig | PermissionSchema): T;
+/**
+ * Attach index definitions to a Zod schema
+ *
+ * This helper function allows you to define PocketBase indexes alongside your
+ * entity schema definitions. The indexes are stored as metadata using Zod's
+ * describe() method and will be extracted during migration generation.
+ *
+ * @param schema - The Zod schema to attach indexes to
+ * @param indexes - Array of PocketBase index SQL statements
+ * @returns The schema with index metadata attached
+ *
+ * @example
+ * // Define indexes for a user schema
+ * const UserSchema = withIndexes(
+ *   withPermissions(
+ *     z.object({ name: z.string(), email: z.string().email() }),
+ *     userPermissions
+ *   ),
+ *   [
+ *     'CREATE UNIQUE INDEX idx_users_email ON users (email)',
+ *     'CREATE INDEX idx_users_name ON users (name)'
+ *   ]
+ * );
+ *
+ * @example
+ * // Single index
+ * const ProjectSchema = withIndexes(
+ *   ProjectDatabaseSchema,
+ *   ['CREATE INDEX idx_projects_status ON projects (status)']
+ * );
+ */
+declare function withIndexes<T extends z.ZodTypeAny>(schema: T, indexes: string[]): T;
+
+/**
+ * Predefined permission templates for common access control patterns
+ */
+declare const PermissionTemplates: {
+    /**
+     * Public access - anyone can perform all operations
+     */
+    public: () => PermissionSchema;
+    /**
+     * Authenticated users only - requires valid authentication for all operations
+     */
+    authenticated: () => PermissionSchema;
+    /**
+     * Owner-only access - users can only manage their own records
+     * @param ownerField - Name of the relation field pointing to user (default: 'User')
+     */
+    ownerOnly: (ownerField?: string) => PermissionSchema;
+    /**
+     * Admin/superuser only access
+     * Assumes a 'role' field exists with 'admin' value
+     * @param roleField - Name of the role field (default: 'role')
+     */
+    adminOnly: (roleField?: string) => PermissionSchema;
+    /**
+     * Public read, authenticated write
+     * Anyone can list/view, but only authenticated users can create/update/delete
+     */
+    readPublic: () => PermissionSchema;
+    /**
+     * Locked access - only superusers can perform operations
+     * All rules are set to null (locked)
+     */
+    locked: () => PermissionSchema;
+    /**
+     * Read-only authenticated - authenticated users can read, no write access
+     */
+    readOnlyAuthenticated: () => PermissionSchema;
+};
+/**
+ * Resolve template configuration to concrete permission schema
+ * @param config - Template configuration or direct permission schema
+ * @returns Resolved permission schema with all rules defined
+ */
+declare function resolveTemplate(config: PermissionTemplateConfig): PermissionSchema;
+/**
+ * Check if a configuration is a template config or direct permission schema
+ * @param config - Configuration to check
+ * @returns True if it's a template configuration
+ */
+declare function isTemplateConfig(config: PermissionTemplateConfig | PermissionSchema): config is PermissionTemplateConfig;
+/**
+ * Check if a configuration is a direct permission schema
+ * @param config - Configuration to check
+ * @returns True if it's a direct permission schema
+ */
+declare function isPermissionSchema(config: PermissionTemplateConfig | PermissionSchema): config is PermissionSchema;
+/**
+ * Validation result for permission configuration
+ */
+interface PermissionValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a permission configuration
+ * @param config - Permission configuration to validate
+ * @param isAuthCollection - Whether this is for an auth collection
+ * @returns Validation result
+ */
+declare function validatePermissionConfig(config: PermissionTemplateConfig | PermissionSchema, isAuthCollection?: boolean): PermissionValidationResult;
+/**
+ * Validate a single rule expression for basic syntax
+ * @param expression - Rule expression to validate
+ * @returns Validation result
+ */
+declare function validateRuleExpression(expression: RuleExpression): PermissionValidationResult;
+/**
+ * Create a custom permission schema with type safety
+ * @param permissions - Partial permission schema
+ * @returns Complete permission schema with null defaults
+ */
+declare function createPermissions(permissions: Partial<PermissionSchema>): PermissionSchema;
+/**
+ * Merge multiple permission schemas, with later schemas taking precedence
+ * @param schemas - Permission schemas to merge
+ * @returns Merged permission schema
+ */
+declare function mergePermissions(...schemas: Partial<PermissionSchema>[]): PermissionSchema;
+
+export { PermissionSchema, PermissionTemplateConfig, PermissionTemplates, type PermissionValidationResult, RuleExpression, baseImageFileSchema, baseSchema, baseSchemaWithTimestamps, boolField, createPermissions, dateField, editorField, emailField, fileField, filesField, geoPointField, inputImageFileSchema, isPermissionSchema, isTemplateConfig, jsonField, mergePermissions, numberField, omitImageFilesSchema, relationField, relationsField, resolveTemplate, selectField, textField, urlField, validatePermissionConfig, validateRuleExpression, withIndexes, withPermissions };