pocketbase-zod-schema 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* Migrations Ignored When Snapshot Exists ([5f9ee2b](https://github.com/dastron/pocketbase-zod-schema/commit/5f9ee2bd0739030fb200302caa40b219f48723d0))
+
+## [0.1.3](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v0.1.2...pocketbase-zod-schema-v0.1.3) (2025-12-19)
+
+
+### Bug Fixes
+
+* Add Relationship Field ([7cc8ff4](https://github.com/dastron/pocketbase-zod-schema/commit/7cc8ff4264219014feeb6ca0a8d8a411dca02eb2))
+* Repair Initial State and Generated Files ([4cd5c62](https://github.com/dastron/pocketbase-zod-schema/commit/4cd5c62ed995f3150ec7eacd39ddeaf1958b2f07))
+
 ## [0.1.2](https://github.com/dastron/pocketbase-zod-schema/compare/pocketbase-zod-schema-v0.1.1...pocketbase-zod-schema-v0.1.2) (2025-12-19)
 
 

package/README.md

@@ -1,22 +1,17 @@
-# PocketBase Zod Migration Package
+# pocketbase-zod-schema
 
-This is the **published NPM package**: `pocketbase-zod-schema`.
+Define your PocketBase collections using Zod schemas and automatically generate migration files.
 
-If you're here from NPM, you can ignore the monorepo details — everything you need to **install and use** the library/CLI is below.
+## Features
 
-## Structure
+- **Type-safe schema definitions** - Use Zod to define your PocketBase collections with full TypeScript support
+- **Automatic migrations** - Generate PocketBase-compatible migration files from your schema changes
+- **Relation support** - Easily define single and multiple relations between collections
+- **Permission templates** - Built-in templates for common permission patterns
+- **Index definitions** - Declare indexes alongside your schema
+- **CLI & programmatic API** - Use the CLI for quick generation or the API for custom workflows
 
-- `src/` - TypeScript source code
-- `dist/` - Built output (generated by tsup)
-- `package.json` - Package configuration and dependencies
-- `tsconfig.json` - TypeScript configuration
-- `tsup.config.ts` - Build configuration
-- `vitest.config.ts` - Test configuration
-- `.prettierrc` - Code formatting configuration
-- `nodemon.json` - Development server configuration
-- `.npmignore` - Files to exclude from npm package
-
-## Installation (NPM)
+## Installation
 
 ```bash
 npm install pocketbase-zod-schema
@@ -26,28 +21,47 @@ yarn add pocketbase-zod-schema
 pnpm add pocketbase-zod-schema
 ```
 
-## Usage
-
-### CLI (`pocketbase-migrate`)
-
-The package ships a CLI named `pocketbase-migrate`.
+## Quick Start
 
-```bash
-# generate migrations from schema changes
-npx pocketbase-migrate generate
+### 1. Create a schema file
 
-# show migration status without writing files
-npx pocketbase-migrate status
+Create a schema file in your project (e.g., `src/schema/post.ts`):
 
-# force generation even if destructive changes are detected
-npx pocketbase-migrate generate --force
+```typescript
+import { z } from "zod";
+import {
+  relationField,
+  relationsField,
+  withPermissions,
+} 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 }),
+  }),
+  {
+    listRule: '@request.auth.id != ""',
+    viewRule: "",
+    createRule: '@request.auth.id != ""',
+    updateRule: "author = @request.auth.id",
+    deleteRule: "author = @request.auth.id",
+  }
+);
 ```
 
-### Configuration
+### 2. Configure the CLI
 
-Create a `pocketbase-migrate.config.js` at your project root:
+Create `pocketbase-migrate.config.js` at your project root:
 
-```js
+```javascript
 export default {
   schema: {
     directory: "./src/schema",
@@ -55,113 +69,329 @@ export default {
   },
   migrations: {
     directory: "./pocketbase/pb_migrations",
-    format: "js",
-  },
-  diff: {
-    warnOnDelete: true,
-    requireForceForDestructive: true,
   },
 };
 ```
 
-### Defining schemas (Zod)
+### 3. Generate migrations
 
-```ts
-import { z } from "zod";
-import { baseSchema, withPermissions } from "pocketbase-zod-schema/schema";
+```bash
+npx pocketbase-migrate generate
+```
 
-export const UserInputSchema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-  avatar: z.string().optional(),
-  role: z.enum(["user", "admin"]).default("user"),
+This will create a migration file in your PocketBase migrations directory.
+
+---
+
+## Schema Definition
+
+### Field Types
+
+The library maps Zod types to PocketBase field types automatically:
+
+| Zod Type | PocketBase Type | Example |
+|----------|-----------------|---------|
+| `z.string()` | text | `title: z.string()` |
+| `z.string().email()` | email | `email: z.string().email()` |
+| `z.string().url()` | url | `website: z.string().url()` |
+| `z.number()` | number | `price: z.number()` |
+| `z.boolean()` | bool | `active: z.boolean()` |
+| `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" })` |
+
+### Defining Relations
+
+Use `relationField()` for single relations and `relationsField()` for multiple relations:
+
+```typescript
+import { relationField, relationsField } from "pocketbase-zod-schema/schema";
+
+const ProjectSchema = z.object({
+  name: z.string(),
+  
+  // Single relation (maxSelect: 1)
+  owner: relationField({ collection: "users" }),
+  
+  // Single relation with cascade delete
+  category: relationField({ 
+    collection: "categories",
+    cascadeDelete: true,
+  }),
+  
+  // Multiple relations (maxSelect: 999 by default)
+  collaborators: relationsField({ collection: "users" }),
+  
+  // Multiple relations with constraints
+  tags: relationsField({ 
+    collection: "tags",
+    minSelect: 1,
+    maxSelect: 5,
+  }),
 });
+```
 
-export const UserSchema = withPermissions(
-  baseSchema.extend(UserInputSchema.shape),
+#### Relation Options
+
+**`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
+- `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`)
+- `maxSelect?: number` - Maximum number of relations allowed (default: `999`)
+
+### Defining Permissions
+
+Use `withPermissions()` to attach API rules to your schema:
+
+```typescript
+import { withPermissions } from "pocketbase-zod-schema/schema";
+
+// Using direct rules
+const PostSchema = withPermissions(
+  z.object({ title: z.string() }),
   {
-    listRule: '@request.auth.id != ""',
-    viewRule: '@request.auth.id != ""',
-    createRule: "",
-    updateRule: "@request.auth.id = id",
-    deleteRule: "@request.auth.id = id",
+    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" }) }),
+  {
+    template: "owner-only",
+    ownerField: "owner",
   }
 );
 ```
 
-### Programmatic usage
+#### Permission Templates
 
-```ts
-import {
-  parseSchemaFiles,
-  compare,
-  generate,
-  loadSnapshotIfExists,
-} from "pocketbase-zod-schema/migration";
+| Template | Description |
+|----------|-------------|
+| `"public"` | All operations are public (no auth required) |
+| `"authenticated"` | All operations require authentication |
+| `"owner-only"` | Only the owner can perform operations |
 
-const migrationsDir = "./pocketbase/pb_migrations";
+#### Template with Custom Overrides
 
-const currentSchema = await parseSchemaFiles("./src/schema");
-const previousSnapshot = loadSnapshotIfExists({ migrationsPath: migrationsDir });
+```typescript
+const PostSchema = withPermissions(schema, {
+  template: "owner-only",
+  ownerField: "author",
+  customRules: {
+    listRule: '@request.auth.id != ""',  // Override just the list rule
+    viewRule: "",                         // Make viewing public
+  },
+});
+```
 
-const diff = compare(currentSchema, previousSnapshot);
-const migrationPath = generate(diff, migrationsDir);
-console.log({ migrationPath });
+### Defining Indexes
+
+Use `withIndexes()` to define database indexes:
+
+```typescript
+import { withIndexes, withPermissions } from "pocketbase-zod-schema/schema";
+
+const UserSchema = withIndexes(
+  withPermissions(
+    z.object({
+      email: z.string().email(),
+      username: z.string(),
+    }),
+    { template: "authenticated" }
+  ),
+  [
+    'CREATE UNIQUE INDEX idx_users_email ON users (email)',
+    'CREATE INDEX idx_users_username ON users (username)',
+  ]
+);
 ```
 
-## Development (repo contributors)
+---
 
-From the root directory, you can run:
+## CLI Reference
+
+### Commands
 
 ```bash
-# Build the package
-yarn build
+# Generate migration from schema changes
+npx pocketbase-migrate generate
 
-# Run tests
-yarn test
+# Show what would be generated without writing files
+npx pocketbase-migrate status
 
-# Start development mode
-yarn dev
+# Force generation even with destructive changes
+npx pocketbase-migrate generate --force
+```
 
-# Format code
-yarn format
+### Configuration Options
 
-# Lint code
-yarn lint
+```javascript
+// pocketbase-migrate.config.js
+export default {
+  schema: {
+    // Directory containing your Zod schema files
+    directory: "./src/schema",
+    
+    // Files to exclude from schema discovery
+    exclude: ["*.test.ts", "*.spec.ts", "base.ts", "index.ts"],
+  },
+  migrations: {
+    // Directory to output migration files
+    directory: "./pocketbase/pb_migrations",
+  },
+  diff: {
+    // Warn when collections or fields would be deleted
+    warnOnDelete: true,
+    
+    // Require --force flag for destructive changes
+    requireForceForDestructive: true,
+  },
+};
 ```
 
-All commands are proxied through the root package.json to this workspace.
+---
 
-## Publishing
+## Programmatic API
 
-Publishing is handled by GitHub Actions (Release Please).
+For custom workflows, use the programmatic API:
 
-### Manual publish (maintainers)
-
-If you need to publish manually, use the **same command as CI**. It only requires `NPM_TOKEN`.
+```typescript
+import {
+  parseSchemaFiles,
+  compare,
+  generate,
+  loadSnapshotIfExists,
+} from "pocketbase-zod-schema/migration";
 
-```bash
-export NPM_TOKEN="***"
-yarn publish:npm
+async function generateMigration() {
+  const schemaDir = "./src/schema";
+  const migrationsDir = "./pocketbase/pb_migrations";
+
+  // Parse all schema files
+  const currentSchema = await parseSchemaFiles(schemaDir);
+
+  // Load the last known state from existing migrations
+  const previousSnapshot = loadSnapshotIfExists({ 
+    migrationsPath: migrationsDir 
+  });
+
+  // Compare schemas and detect changes
+  const diff = compare(currentSchema, previousSnapshot);
+
+  // Generate migration file
+  if (diff.collectionsToCreate.length > 0 || 
+      diff.collectionsToModify.length > 0 || 
+      diff.collectionsToDelete.length > 0) {
+    const migrationPath = generate(diff, migrationsDir);
+    console.log(`Migration created: ${migrationPath}`);
+  } else {
+    console.log("No changes detected");
+  }
+}
 ```
 
-If you'd rather keep the token in a local `.env` file (gitignored), you can do:
+---
 
-```bash
-echo 'NPM_TOKEN="***"' > .env
-yarn publish:npm:env
-```
+## Complete Example
 
-If your npm org/account requires publish-time 2FA, either:
+Here's a complete example of a blog schema with users, posts, and comments:
 
-- use an **automation / granular token** configured to bypass 2FA for publishing (recommended for CI), or
-- set a one-time password for local publishing:
+```typescript
+// src/schema/user.ts
+import { z } from "zod";
+import { withPermissions, withIndexes } from "pocketbase-zod-schema/schema";
+
+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",
+    }
+  ),
+  [
+    'CREATE UNIQUE INDEX idx_users_email ON users (email)',
+  ]
+);
+```
 
-```bash
-export NPM_OTP="123456"
-yarn publish:npm:env
+```typescript
+// src/schema/post.ts
+import { z } from "zod";
+import { 
+  relationField, 
+  relationsField, 
+  withPermissions 
+} 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 }),
+  }),
+  {
+    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";
+
+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" }),
+  }),
+  {
+    listRule: "",
+    viewRule: "",
+    createRule: '@request.auth.id != ""',
+    updateRule: "author = @request.auth.id",
+    deleteRule: "author = @request.auth.id || @request.auth.role = 'admin'",
+  }
+);
 ```
 
-Authentication options:
+---
+
+## License
 
-- set `NPM_TOKEN` in your shell for the command
+MIT