pocketbase-zod-schema 0.2.4 → 0.3.0

package/dist/fields-UcOPu1OQ.d.ts

@@ -0,0 +1,364 @@
+import { z } from 'zod';
+
+/**
+ * Internal marker for field metadata
+ * Used by the migration generator to detect explicit field type definitions
+ */
+declare const FIELD_METADATA_KEY = "__pocketbase_field__";
+/**
+ * PocketBase field types
+ */
+type PocketBaseFieldType = "text" | "email" | "url" | "editor" | "number" | "bool" | "date" | "autodate" | "select" | "relation" | "file" | "json" | "geoPoint";
+/**
+ * Field metadata structure embedded in Zod schema descriptions
+ */
+interface FieldMetadata {
+    type: PocketBaseFieldType;
+    options?: Record<string, any>;
+}
+/**
+ * Extracts field metadata from a Zod type's description
+ * Used by the migration generator to detect explicit field type definitions
+ *
+ * @param description - The Zod type's description string
+ * @returns Field metadata if present, null otherwise
+ *
+ * @example
+ * const schema = TextField({ min: 1, max: 100 });
+ * const metadata = extractFieldMetadata(schema.description);
+ * // Returns: { type: "text", options: { min: 1, max: 100 } }
+ */
+declare function extractFieldMetadata(description: string | undefined): FieldMetadata | null;
+/**
+ * Text field configuration options
+ */
+interface TextFieldOptions {
+    /**
+     * Minimum length constraint
+     */
+    min?: number;
+    /**
+     * Maximum length constraint
+     */
+    max?: number;
+    /**
+     * Pattern constraint (regex)
+     */
+    pattern?: RegExp | string;
+    /**
+     * Auto-generate pattern for automatic value generation
+     * Example: "[A-Z]{3}-[0-9]{6}" generates values like "ABC-123456"
+     */
+    autogeneratePattern?: string;
+}
+/**
+ * Number field configuration options
+ */
+interface NumberFieldOptions {
+    /**
+     * Minimum value constraint
+     */
+    min?: number;
+    /**
+     * Maximum value constraint
+     */
+    max?: number;
+    /**
+     * Whether to disallow decimal values (integers only)
+     */
+    noDecimal?: boolean;
+    /**
+     * Whether the field is required
+     * @default false
+     *
+     * Note: In PocketBase, `required: true` for number fields means the value must be non-zero.
+     * If you want to allow zero values (e.g., for progress: 0-100), keep this as `false`.
+     * Set to `true` only if you want to enforce non-zero values.
+     */
+    required?: boolean;
+}
+/**
+ * Date field configuration options
+ */
+interface DateFieldOptions {
+    /**
+     * Minimum date constraint
+     */
+    min?: Date | string;
+    /**
+     * Maximum date constraint
+     */
+    max?: Date | string;
+}
+/**
+ * Autodate field configuration options
+ */
+interface AutodateFieldOptions {
+    /**
+     * Set date automatically on record creation
+     * @default false
+     */
+    onCreate?: boolean;
+    /**
+     * Update date automatically on record update
+     * @default false
+     */
+    onUpdate?: boolean;
+}
+/**
+ * Select field configuration options
+ */
+interface SelectFieldOptions {
+    /**
+     * Maximum number of selections allowed
+     * If > 1, enables multiple selection
+     * @default 1
+     */
+    maxSelect?: number;
+}
+/**
+ * File field configuration options
+ */
+interface FileFieldOptions {
+    /**
+     * Allowed MIME types
+     * Example: ["image/*", "application/pdf"]
+     */
+    mimeTypes?: string[];
+    /**
+     * Maximum file size in bytes
+     */
+    maxSize?: number;
+    /**
+     * Thumbnail sizes to generate
+     * Example: ["100x100", "200x200"]
+     */
+    thumbs?: string[];
+    /**
+     * Whether the file is protected (requires auth to access)
+     * @default false
+     */
+    protected?: boolean;
+}
+/**
+ * Multiple files field configuration options
+ */
+interface FilesFieldOptions extends FileFieldOptions {
+    /**
+     * Minimum number of files required
+     */
+    minSelect?: number;
+    /**
+     * Maximum number of files allowed
+     */
+    maxSelect?: number;
+}
+/**
+ * Creates a boolean field schema
+ * Maps to PocketBase 'bool' field type
+ *
+ * @returns Zod boolean schema with PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   active: BoolField(),
+ *   featured: BoolField().optional(),
+ * });
+ */
+declare function BoolField(): z.ZodBoolean;
+/**
+ * Creates a number field schema with optional constraints
+ * Maps to PocketBase 'number' field type
+ *
+ * @param options - Optional constraints for the number field
+ * @returns Zod number schema with PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   price: NumberField({ min: 0 }),
+ *   quantity: NumberField({ min: 0, noDecimal: true }),
+ *   rating: NumberField({ min: 0, max: 5 }),
+ *   progress: NumberField({ min: 0, max: 100 }), // required defaults to false, allowing zero
+ *   score: NumberField({ min: 1, max: 10, required: true }), // requires non-zero value
+ * });
+ *
+ * @remarks
+ * By default, number fields are not required (`required: false`), which allows zero values.
+ * In PocketBase, `required: true` for number fields means the value must be non-zero.
+ * If you set `min: 0` and want to allow zero, keep `required: false` (the default).
+ */
+declare function NumberField(options?: NumberFieldOptions): z.ZodNumber;
+/**
+ * Creates a text field schema with optional constraints
+ * Maps to PocketBase 'text' field type
+ *
+ * @param options - Optional constraints for the text field
+ * @returns Zod string schema with PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   name: TextField({ min: 1, max: 200 }),
+ *   sku: TextField({ autogeneratePattern: "[A-Z]{3}-[0-9]{6}" }),
+ *   description: TextField({ max: 1000 }),
+ * });
+ */
+declare function TextField(options?: TextFieldOptions): z.ZodString;
+/**
+ * Creates an email field schema
+ * Maps to PocketBase 'email' field type
+ *
+ * @returns Zod string schema with email validation and PocketBase metadata
+ *
+ * @example
+ * const UserSchema = z.object({
+ *   email: EmailField(),
+ *   alternateEmail: EmailField().optional(),
+ * });
+ */
+declare function EmailField(): z.ZodString;
+/**
+ * Creates a URL field schema
+ * Maps to PocketBase 'url' field type
+ *
+ * @returns Zod string schema with URL validation and PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   website: URLField(),
+ *   documentation: URLField().optional(),
+ * });
+ */
+declare function URLField(): z.ZodString;
+/**
+ * Creates a rich text editor field schema
+ * Maps to PocketBase 'editor' field type
+ *
+ * @returns Zod string schema with PocketBase metadata
+ *
+ * @example
+ * const PostSchema = z.object({
+ *   content: EditorField(),
+ *   summary: EditorField().optional(),
+ * });
+ */
+declare function EditorField(): z.ZodString;
+/**
+ * Creates a date field schema with optional constraints
+ * Maps to PocketBase 'date' field type
+ *
+ * @param options - Optional date constraints
+ * @returns Zod string schema with PocketBase metadata
+ *
+ * @example
+ * const EventSchema = z.object({
+ *   startDate: DateField(),
+ *   endDate: DateField({ min: new Date('2024-01-01') }),
+ *   releaseDate: DateField().optional(),
+ * });
+ */
+declare function DateField(options?: DateFieldOptions): z.ZodString;
+/**
+ * Creates an autodate field schema with automatic timestamp management
+ * Maps to PocketBase 'autodate' field type
+ *
+ * @param options - Optional autodate configuration
+ * @returns Zod string schema with PocketBase metadata
+ *
+ * @example
+ * const PostSchema = z.object({
+ *   createdAt: AutodateField({ onCreate: true }),
+ *   updatedAt: AutodateField({ onUpdate: true }),
+ *   publishedAt: AutodateField({ onCreate: true, onUpdate: false }),
+ * });
+ */
+declare function AutodateField(options?: AutodateFieldOptions): z.ZodString;
+/**
+ * Creates a select field schema from enum values
+ * Maps to PocketBase 'select' field type
+ *
+ * @param values - Array of allowed string values
+ * @param options - Optional select configuration
+ * @returns Zod enum or array schema with PocketBase metadata
+ *
+ * @example
+ * // Single select
+ * const PostSchema = z.object({
+ *   status: SelectField(["draft", "published", "archived"]),
+ * });
+ *
+ * @example
+ * // Multiple select
+ * const ProductSchema = z.object({
+ *   categories: SelectField(["electronics", "clothing", "food"], { maxSelect: 3 }),
+ * });
+ */
+declare function SelectField<T extends [string, ...string[]]>(values: T, options?: SelectFieldOptions): z.ZodEnum<T> | z.ZodArray<z.ZodEnum<T>>;
+/**
+ * Creates a single file field schema
+ * Maps to PocketBase 'file' field type with maxSelect=1
+ *
+ * @param options - Optional file constraints
+ * @returns Zod File schema with PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   thumbnail: FileField({ mimeTypes: ["image/*"], maxSize: 5242880 }),
+ *   document: FileField({ mimeTypes: ["application/pdf"] }),
+ * });
+ */
+declare function FileField(options?: FileFieldOptions): z.ZodType<File>;
+/**
+ * Creates a multiple files field schema
+ * Maps to PocketBase 'file' field type with maxSelect>1
+ *
+ * @param options - Optional file constraints
+ * @returns Zod array of File schema with PocketBase metadata
+ *
+ * @example
+ * const ProductSchema = z.object({
+ *   images: FilesField({ mimeTypes: ["image/*"], maxSelect: 5 }),
+ *   attachments: FilesField({ minSelect: 1, maxSelect: 10 }),
+ * });
+ */
+declare function FilesField(options?: FilesFieldOptions): z.ZodArray<z.ZodType<File>>;
+/**
+ * Creates a JSON field schema with optional inner schema validation
+ * Maps to PocketBase 'json' field type
+ *
+ * @param schema - Optional Zod schema for the JSON structure
+ * @returns Zod schema with PocketBase metadata
+ *
+ * @example
+ * // Any JSON
+ * const ProductSchema = z.object({
+ *   metadata: JSONField(),
+ * });
+ *
+ * @example
+ * // Typed JSON
+ * const ProductSchema = z.object({
+ *   settings: JSONField(z.object({
+ *     theme: z.string(),
+ *     notifications: z.boolean(),
+ *   })),
+ * });
+ */
+declare function JSONField<T extends z.ZodTypeAny>(schema?: T): T | z.ZodRecord<z.ZodString, z.ZodAny>;
+/**
+ * Creates a geographic point field schema
+ * Maps to PocketBase 'geoPoint' field type
+ *
+ * @returns Zod object schema with lon/lat fields and PocketBase metadata
+ *
+ * @example
+ * const LocationSchema = z.object({
+ *   coordinates: GeoPointField(),
+ *   homeLocation: GeoPointField().optional(),
+ * });
+ */
+declare function GeoPointField(): z.ZodObject<{
+    lon: z.ZodNumber;
+    lat: z.ZodNumber;
+}>;
+
+export { type AutodateFieldOptions as A, BoolField as B, type DateFieldOptions as D, EmailField as E, FIELD_METADATA_KEY as F, GeoPointField as G, JSONField as J, type NumberFieldOptions as N, type PocketBaseFieldType as P, type SelectFieldOptions as S, type TextFieldOptions as T, URLField as U, type FieldMetadata as a, type FileFieldOptions as b, type FilesFieldOptions as c, NumberField as d, extractFieldMetadata as e, TextField as f, EditorField as g, DateField as h, AutodateField as i, SelectField as j, FileField as k, FilesField as l };