pocketbase-zod-schema 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.0](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v0.1.4...pocketbase-zod-schema-v0.2.0) (2025-12-20)
+
+
+### Features
+
+* Add `defineCollection` to wrap schema definition ([8dbcbfa](https://github.com/dastron/pocketbase-zod-schema/commit/8dbcbfae1833509578a63e942847349cceea6cf3))
+
 ## [0.1.4](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v0.1.3...pocketbase-zod-schema-v0.1.4) (2025-12-20)
 
 

package/README.md

@@ -30,31 +30,36 @@ Create a schema file in your project (e.g., `src/schema/post.ts`):
 ```typescript
 import { z } from "zod";
 import {
-  relationField,
-  relationsField,
-  withPermissions,
+  defineCollection,
+  RelationField,
+  RelationsField,
 } from "pocketbase-zod-schema/schema";
 
-export const PostSchema = withPermissions(
-  z.object({
-    title: z.string().min(1).max(200),
-    content: z.string(),
-    published: z.boolean().default(false),
-    
-    // Single relation to users collection
-    author: relationField({ collection: "users" }),
-    
-    // Multiple relations to tags collection
-    tags: relationsField({ collection: "tags", maxSelect: 10 }),
-  }),
-  {
+// Define the Zod schema
+export const PostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string(),
+  published: z.boolean().default(false),
+  
+  // Single relation to users collection
+  author: RelationField({ collection: "users" }),
+  
+  // Multiple relations to tags collection
+  tags: RelationsField({ collection: "tags", maxSelect: 10 }),
+});
+
+// Define the collection with permissions
+export const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: PostSchema,
+  permissions: {
     listRule: '@request.auth.id != ""',
     viewRule: "",
     createRule: '@request.auth.id != ""',
     updateRule: "author = @request.auth.id",
     deleteRule: "author = @request.auth.id",
-  }
-);
+  },
+});
 ```
 
 ### 2. Configure the CLI
@@ -81,10 +86,69 @@ npx pocketbase-migrate generate
 
 This will create a migration file in your PocketBase migrations directory.
 
+**TypeScript Support:** You can use TypeScript (`.ts`) schema files directly - no compilation needed! The tool automatically handles TypeScript files using `tsx`.
+
 ---
 
 ## Schema Definition
 
+### High-Level Collection Definition
+
+The recommended way to define collections is using `defineCollection()`, which provides a single entry point for collection name, schema, permissions, indexes, and future features:
+
+```typescript
+import { z } from "zod";
+import { defineCollection, RelationField } from "pocketbase-zod-schema/schema";
+
+export const PostCollectionSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  author: RelationField({ collection: "users" }),
+});
+
+export const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: PostCollectionSchema,
+  permissions: {
+    template: "owner-only",
+    ownerField: "author",
+  },
+  indexes: [
+    "CREATE INDEX idx_posts_author ON posts (author)",
+  ],
+});
+```
+
+**Benefits of `defineCollection()`:**
+- **Explicit collection name** - No need to rely on filename conventions
+- **All metadata in one place** - Schema, permissions, indexes together
+- **Future-proof** - Easy to extend with new features
+- **Cleaner syntax** - No nested function calls
+
+**Export Pattern:** It's recommended to export both the schema and collection definition:
+
+```typescript
+// Define the Zod schema (for type inference and validation)
+export const PostSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  author: RelationField({ collection: "users" }),
+});
+
+// Define the collection (used by migration generator, includes metadata)
+export const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: PostSchema,
+  permissions: { /* ... */ },
+});
+```
+
+This pattern allows:
+- `PostSchema` - Used for type inference (`z.infer<typeof PostSchema>`) and validation
+- `PostCollection` - Used by the migration generator (has collection metadata)
+
+**Note:** You can still use `withPermissions()` and `withIndexes()` separately if you prefer, but `defineCollection()` is recommended for new code.
+
 ### Field Types
 
 The library maps Zod types to PocketBase field types automatically:
@@ -99,33 +163,33 @@ The library maps Zod types to PocketBase field types automatically:
 | `z.date()` | date | `birthdate: z.date()` |
 | `z.enum([...])` | select | `status: z.enum(["draft", "published"])` |
 | `z.instanceof(File)` | file | `avatar: z.instanceof(File)` |
-| `relationField()` | relation | `author: relationField({ collection: "users" })` |
-| `relationsField()` | relation | `tags: relationsField({ collection: "tags" })` |
+| `RelationField()` | relation | `author: RelationField({ collection: "users" })` |
+| `RelationsField()` | relation | `tags: RelationsField({ collection: "tags" })` |
 
 ### Defining Relations
 
-Use `relationField()` for single relations and `relationsField()` for multiple relations:
+Use `RelationField()` for single relations and `RelationsField()` for multiple relations:
 
 ```typescript
-import { relationField, relationsField } from "pocketbase-zod-schema/schema";
+import { RelationField, RelationsField } from "pocketbase-zod-schema/schema";
 
 const ProjectSchema = z.object({
   name: z.string(),
   
   // Single relation (maxSelect: 1)
-  owner: relationField({ collection: "users" }),
+  owner: RelationField({ collection: "users" }),
   
   // Single relation with cascade delete
-  category: relationField({ 
+  category: RelationField({ 
     collection: "categories",
     cascadeDelete: true,
   }),
   
   // Multiple relations (maxSelect: 999 by default)
-  collaborators: relationsField({ collection: "users" }),
+  collaborators: RelationsField({ collection: "users" }),
   
   // Multiple relations with constraints
-  tags: relationsField({ 
+  tags: RelationsField({ 
     collection: "tags",
     minSelect: 1,
     maxSelect: 5,
@@ -135,11 +199,11 @@ const ProjectSchema = z.object({
 
 #### Relation Options
 
-**`relationField(config)`** - Single relation
+**`RelationField(config)`** - Single relation
 - `collection: string` - Target collection name (required)
 - `cascadeDelete?: boolean` - Delete related records when this record is deleted (default: `false`)
 
-**`relationsField(config)`** - Multiple relations
+**`RelationsField(config)`** - Multiple relations
 - `collection: string` - Target collection name (required)
 - `cascadeDelete?: boolean` - Delete related records when this record is deleted (default: `false`)
 - `minSelect?: number` - Minimum number of relations required (default: `0`)
@@ -147,29 +211,43 @@ const ProjectSchema = z.object({
 
 ### Defining Permissions
 
-Use `withPermissions()` to attach API rules to your schema:
+Use `defineCollection()` with permissions, or `withPermissions()` to attach API rules to your schema:
 
 ```typescript
-import { withPermissions } from "pocketbase-zod-schema/schema";
+import { defineCollection, withPermissions } from "pocketbase-zod-schema/schema";
 
-// Using direct rules
-const PostSchema = withPermissions(
-  z.object({ title: z.string() }),
-  {
+// Using defineCollection (recommended)
+const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: z.object({ title: z.string() }),
+  permissions: {
     listRule: '@request.auth.id != ""',     // Authenticated users can list
     viewRule: "",                            // Anyone can view (public)
     createRule: '@request.auth.id != ""',   // Authenticated users can create
     updateRule: "author = @request.auth.id", // Only author can update
     deleteRule: "author = @request.auth.id", // Only author can delete
-  }
-);
+  },
+});
 
-// Using templates
-const ProjectSchema = withPermissions(
-  z.object({ title: z.string(), owner: relationField({ collection: "users" }) }),
-  {
+// Using templates with defineCollection
+const ProjectCollection = defineCollection({
+  collectionName: "projects",
+  schema: z.object({ title: z.string(), owner: RelationField({ collection: "users" }) }),
+  permissions: {
     template: "owner-only",
     ownerField: "owner",
+  },
+});
+
+// Using withPermissions (alternative approach)
+const PostSchemaAlt = withPermissions(
+  z.object({ title: z.string() }),
+  {
+    listRule: '@request.auth.id != ""',
+    viewRule: "",
+    createRule: '@request.auth.id != ""',
+    updateRule: "author = @request.auth.id",
+    deleteRule: "author = @request.auth.id",
   }
 );
 ```
@@ -185,24 +263,56 @@ const ProjectSchema = withPermissions(
 #### Template with Custom Overrides
 
 ```typescript
-const PostSchema = withPermissions(schema, {
+// Using defineCollection (recommended)
+const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: z.object({ title: z.string(), author: RelationField({ collection: "users" }) }),
+  permissions: {
+    template: "owner-only",
+    ownerField: "author",
+    customRules: {
+      listRule: '@request.auth.id != ""',  // Override just the list rule
+      viewRule: "",                         // Make viewing public
+    },
+  },
+});
+
+// Using withPermissions (alternative)
+const PostSchemaAlt = withPermissions(schema, {
   template: "owner-only",
   ownerField: "author",
   customRules: {
-    listRule: '@request.auth.id != ""',  // Override just the list rule
-    viewRule: "",                         // Make viewing public
+    listRule: '@request.auth.id != ""',
+    viewRule: "",
   },
 });
 ```
 
 ### Defining Indexes
 
-Use `withIndexes()` to define database indexes:
+Use `defineCollection()` with indexes, or `withIndexes()` to define database indexes:
 
 ```typescript
-import { withIndexes, withPermissions } from "pocketbase-zod-schema/schema";
+import { defineCollection, withIndexes, withPermissions } from "pocketbase-zod-schema/schema";
+
+// Using defineCollection (recommended)
+const UserCollection = defineCollection({
+  collectionName: "users",
+  schema: z.object({
+    email: z.string().email(),
+    username: z.string(),
+  }),
+  permissions: {
+    template: "authenticated",
+  },
+  indexes: [
+    'CREATE UNIQUE INDEX idx_users_email ON users (email)',
+    'CREATE INDEX idx_users_username ON users (username)',
+  ],
+});
 
-const UserSchema = withIndexes(
+// Using withIndexes (alternative)
+const UserSchemaAlt = withIndexes(
   withPermissions(
     z.object({
       email: z.string().email(),
@@ -310,84 +420,109 @@ Here's a complete example of a blog schema with users, posts, and comments:
 ```typescript
 // src/schema/user.ts
 import { z } from "zod";
-import { withPermissions, withIndexes } from "pocketbase-zod-schema/schema";
+import { baseSchema, defineCollection } from "pocketbase-zod-schema/schema";
+
+// Input schema for forms (includes passwordConfirm for validation)
+export const UserInputSchema = z.object({
+  name: z.string().optional(),
+  email: z.string().email(),
+  password: z.string().min(8),
+  passwordConfirm: z.string(),
+  avatar: z.instanceof(File).optional(),
+});
 
-export const UserSchema = withIndexes(
-  withPermissions(
-    z.object({
-      name: z.string().optional(),
-      email: z.string().email(),
-      password: z.string().min(8),
-      avatar: z.instanceof(File).optional(),
-    }),
-    {
-      listRule: "id = @request.auth.id",
-      viewRule: "id = @request.auth.id",
-      createRule: "",
-      updateRule: "id = @request.auth.id",
-      deleteRule: "id = @request.auth.id",
-    }
-  ),
-  [
+// Database schema (excludes passwordConfirm)
+const UserCollectionSchema = z.object({
+  name: z.string().optional(),
+  email: z.string().email(),
+  password: z.string().min(8),
+  avatar: z.instanceof(File).optional(),
+});
+
+// Full schema with base fields for type inference (includes id, collectionId, etc.)
+export const UserSchema = UserCollectionSchema.extend(baseSchema);
+
+// Collection definition with permissions and indexes
+export const UserCollection = defineCollection({
+  collectionName: "Users",
+  schema: UserSchema,
+  permissions: {
+    listRule: "id = @request.auth.id",
+    viewRule: "id = @request.auth.id",
+    createRule: "",
+    updateRule: "id = @request.auth.id",
+    deleteRule: "id = @request.auth.id",
+  },
+  indexes: [
     'CREATE UNIQUE INDEX idx_users_email ON users (email)',
-  ]
-);
+  ],
+});
 ```
 
 ```typescript
 // src/schema/post.ts
 import { z } from "zod";
 import { 
-  relationField, 
-  relationsField, 
-  withPermissions 
+  defineCollection,
+  RelationField, 
+  RelationsField, 
 } from "pocketbase-zod-schema/schema";
 
-export const PostSchema = withPermissions(
-  z.object({
-    title: z.string().min(1).max(200),
-    slug: z.string(),
-    content: z.string(),
-    excerpt: z.string().optional(),
-    published: z.boolean().default(false),
-    publishedAt: z.date().optional(),
-    
-    // Relations
-    author: relationField({ collection: "users" }),
-    category: relationField({ collection: "categories" }),
-    tags: relationsField({ collection: "tags", maxSelect: 10 }),
-  }),
-  {
+// Define the Zod schema
+export const PostSchema = z.object({
+  title: z.string().min(1).max(200),
+  slug: z.string(),
+  content: z.string(),
+  excerpt: z.string().optional(),
+  published: z.boolean().default(false),
+  publishedAt: z.date().optional(),
+  
+  // Relations
+  author: RelationField({ collection: "users" }),
+  category: RelationField({ collection: "categories" }),
+  tags: RelationsField({ collection: "tags", maxSelect: 10 }),
+});
+
+// Define the collection with permissions
+export const PostCollection = defineCollection({
+  collectionName: "posts",
+  schema: PostSchema,
+  permissions: {
     listRule: 'published = true || author = @request.auth.id',
     viewRule: 'published = true || author = @request.auth.id',
     createRule: '@request.auth.id != ""',
     updateRule: "author = @request.auth.id",
     deleteRule: "author = @request.auth.id",
-  }
-);
+  },
+});
 ```
 
 ```typescript
 // src/schema/comment.ts
 import { z } from "zod";
-import { relationField, withPermissions } from "pocketbase-zod-schema/schema";
+import { defineCollection, RelationField } from "pocketbase-zod-schema/schema";
 
-export const CommentSchema = withPermissions(
-  z.object({
-    content: z.string().min(1),
-    
-    // Relations with cascade delete
-    post: relationField({ collection: "posts", cascadeDelete: true }),
-    author: relationField({ collection: "users" }),
-  }),
-  {
+// Define the Zod schema
+export const CommentSchema = z.object({
+  content: z.string().min(1),
+  
+  // Relations with cascade delete
+  post: RelationField({ collection: "posts", cascadeDelete: true }),
+  author: RelationField({ collection: "users" }),
+});
+
+// Define the collection with permissions
+export const CommentCollection = defineCollection({
+  collectionName: "comments",
+  schema: CommentSchema,
+  permissions: {
     listRule: "",
     viewRule: "",
     createRule: '@request.auth.id != ""',
     updateRule: "author = @request.auth.id",
     deleteRule: "author = @request.auth.id || @request.auth.role = 'admin'",
-  }
-);
+  },
+});
 ```
 
 ---

package/dist/cli/index.cjs

@@ -1076,6 +1076,16 @@ function isFieldRequired(zodType) {
 }
 
 // src/migration/analyzer.ts
+var tsxLoaderRegistered = false;
+async function ensureTsxLoader() {
+  if (tsxLoaderRegistered) return;
+  try {
+    await import('tsx/esm');
+    tsxLoaderRegistered = true;
+  } catch {
+    tsxLoaderRegistered = false;
+  }
+}
 var DEFAULT_CONFIG = {
   workspaceRoot: process.cwd(),
   excludePatterns: [
@@ -1173,24 +1183,37 @@ async function importSchemaModule(filePath, config) {
     } else {
       resolvedPath = jsPath;
     }
+    if (resolvedPath.endsWith(".ts")) {
+      await ensureTsxLoader();
+      if (!tsxLoaderRegistered) {
+        throw new SchemaParsingError(
+          `Failed to import TypeScript schema file. The 'tsx' package is required to load TypeScript files.
+Please install tsx: npm install tsx (or yarn add tsx, or pnpm add tsx)
+Alternatively, compile your schema files to JavaScript first.`,
+          filePath
+        );
+      }
+    }
     const fileUrl = new URL(`file://${path5__namespace.resolve(resolvedPath)}`);
     const module = await import(fileUrl.href);
     return module;
   } catch (error) {
     const tsPath = `${filePath}.ts`;
     const isTypeScriptFile = fs5__namespace.existsSync(tsPath);
+    if (isTypeScriptFile && error instanceof SchemaParsingError) {
+      throw error;
+    }
     if (isTypeScriptFile) {
       throw new SchemaParsingError(
-        `Failed to import TypeScript schema file. Node.js cannot import TypeScript files directly.
-Please either:
-  1. Compile your schema files to JavaScript first, or
-  2. Use tsx to run the migration tool (e.g., "npx tsx package/dist/cli/migrate.js status" or "tsx package/dist/cli/migrate.js status")`,
+        `Failed to import TypeScript schema file. The 'tsx' package is required to load TypeScript files.
+Please install tsx: npm install tsx (or yarn add tsx, or pnpm add tsx)
+Alternatively, compile your schema files to JavaScript first.`,
         filePath,
         error
       );
     }
     throw new SchemaParsingError(
-      `Failed to import schema module. Make sure the schema files are compiled to JavaScript.`,
+      `Failed to import schema module. Make sure the schema files exist and are valid.`,
       filePath,
       error
     );
@@ -1200,6 +1223,19 @@ function getCollectionNameFromFile(filePath) {
   const filename = path5__namespace.basename(filePath).replace(/\.(ts|js)$/, "");
   return toCollectionName(filename);
 }
+function extractCollectionNameFromSchema(zodSchema) {
+  if (!zodSchema.description) {
+    return null;
+  }
+  try {
+    const metadata = JSON.parse(zodSchema.description);
+    if (metadata.collectionName && typeof metadata.collectionName === "string") {
+      return metadata.collectionName;
+    }
+  } catch {
+  }
+  return null;
+}
 function extractSchemaDefinitions(module, patterns = ["Schema", "InputSchema"]) {
   const result = {};
   for (const [key, value] of Object.entries(module)) {
@@ -1375,7 +1411,8 @@ async function buildSchemaDefinition(config) {
         console.warn(`No valid schema found in ${filePath}, skipping...`);
         continue;
       }
-      const collectionName = getCollectionNameFromFile(filePath);
+      const collectionNameFromSchema = extractCollectionNameFromSchema(zodSchema);
+      const collectionName = collectionNameFromSchema ?? getCollectionNameFromFile(filePath);
       const collectionSchema = convertZodSchemaToCollectionSchema(collectionName, zodSchema);
       collections.set(collectionName, collectionSchema);
     } catch (error) {