@zanzojs/drizzle 0.1.0-beta.2 → 0.2.0

package/README.md

@@ -1,91 +1,91 @@
 # @zanzojs/drizzle
 
 [![npm version](https://img.shields.io/npm/v/@zanzojs/drizzle.svg?style=flat-square)](https://www.npmjs.com/package/@zanzojs/drizzle)
-[![Drizzle ORM](https://img.shields.io/badge/Drizzle-ORM-green.svg?style=flat-square)](https://orm.drizzle.team/)
+[![Drizzle ORM](https://img.shields.io/badge/Drizzle-ORM-green.svg?style=flat-square)](https://orm.drizzle.team)
 
-The official Drizzle ORM adapter for ZanzoJS. 
+The official Drizzle ORM adapter for ZanzoJS.
 
-Translating complex relationship hierarchies into SQL `JOIN`s is historically messy and slow. This adapter implements the "Zanzibar Tuple Pattern", which translates your Zanzo authorization rules into safe, parameterized `EXISTS` subqueries targeting a single, universal table.
+## When to use this package
 
-## Installation
+`@zanzojs/drizzle` serves two distinct purposes:
+
+**1. Write-time tuple materialization** (`expandTuples` / `collapseTuples`)
+When you grant or revoke access via nested permission paths (e.g. `folder.admin`), you must pre-materialize the derived tuples in the database. This is what makes read-time evaluation fast.
+
+**2. SQL-filtered queries for large datasets**
+When you need to fetch a filtered list of resources (e.g. "all documents this user can read") and the dataset is too large to load entirely into memory, the adapter generates parameterized `EXISTS` subqueries that push the permission filter directly to the database.
+```typescript
+// Without adapter — loads everything into memory and filters (inefficient for large datasets)
+const allDocs = await db.select().from(documents);
+const myDocs = allDocs.filter(d => snapshot['Document:' + d.id]?.includes('read'));
+
+// With adapter — filter goes directly to SQL (efficient at any scale)
+const myDocs = await db.select().from(documents)
+  .where(withPermissions('User:alice', 'read', 'Document', documents.id));
+```
+
+> **Note:** For the frontend snapshot flow, you don't need this adapter. The snapshot is generated by loading the user's tuples with `engine.load()` and calling `createZanzoSnapshot()`. The adapter is for backend queries that need SQL-level filtering.
 
-This package requires `@zanzojs/core` and `drizzle-orm` as peer dependencies.
+## Installation
 
 ```bash
 pnpm add @zanzojs/core @zanzojs/drizzle drizzle-orm
 ```
 
-## Setup Guide
+## Setup
 
-### 1. The Universal Tuple Table
-
-Instead of spreading permission foreign keys across all your tables, you create a single table to hold all application relationships. This table structure is mandatory for the adapter to work.
+### 1. Create the Universal Tuple Table
 
+All relationships live in a single table. This is the Zanzibar pattern.
 ```typescript
-import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
 
 export const zanzoTuples = sqliteTable('zanzo_tuples', {
-  object: text('object').notNull(),     // e.g., "Project:123"
-  relation: text('relation').notNull(), // e.g., "owner"
-  subject: text('subject').notNull(),   // e.g., "User:999"
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  object: text('object').notNull(),     // e.g. "Document:doc1"
+  relation: text('relation').notNull(), // e.g. "owner"
+  subject: text('subject').notNull(),   // e.g. "User:alice"
 });
 ```
 
-### 2. Creating the Adapter
-
-You initialize the adapter by feeding it your core `ZanzoEngine` instance and your Drizzle tuple table reference. 
-
+### 2. Create the adapter
 ```typescript
 import { createZanzoAdapter } from '@zanzojs/drizzle';
-import { engine } from './zanzo.config'; 
+import { engine } from './zanzo.config';
 import { zanzoTuples } from './schema';
 
 export const withPermissions = createZanzoAdapter(engine, zanzoTuples);
 ```
 
-### 3. Query Pushdown (Read Operations)
-
-Now, whenever you want to fetch a list of entities (like `Projects`) but only return the ones the user is allowed to read, you use the adapter to generate the `WHERE` clause dynamically.
-
+### 3. Query pushdown
 ```typescript
-import { db, projects } from './db';
-
-async function getReadableProjects(userId: string) {
-  // Generate the AST SQL fragment
-  const accessFilter = withPermissions(
-    `User:${userId}`, 
-    'read', 
-    'Project', 
-    projects.id // The column to match against the tuple's object ID
-  );
-
-  // Apply it to your standard Drizzle query
-  return await db.select().from(projects).where(accessFilter);
+async function getReadableDocuments(userId: string) {
+  return await db.select()
+    .from(documents)
+    .where(withPermissions(`User:${userId}`, 'read', 'Document', documents.id));
 }
 ```
 
-### Write Operations (Important!)
+## Write Operations
 
-The SQL adapter prioritizes extreme read performance. As a trade-off, it relies on strict string matching for nested definitions (e.g. `workspace.org.admin`). 
-
-To make this work, **you must use `@zanzojs/core`'s `expandTuples()` function when writing to the database.** If you skip `expandTuples()` during mutations, deep permission paths will not resolve correctly during Drizzle queries.
+### Granting access with expandTuples
 
+When assigning a role that involves nested permission paths, use `expandTuples` to materialize all derived tuples atomically.
 ```typescript
 import { expandTuples } from '@zanzojs/core';
 
-async function grantAccess(userId: string, projectId: string) {
+async function grantAccess(userId: string, relation: string, objectId: string) {
   const baseTuple = {
     subject: `User:${userId}`,
-    relation: 'owner',
-    object: `Project:${projectId}`,
+    relation,
+    object: objectId,
   };
 
   const derived = await expandTuples({
     schema: engine.getSchema(),
     newTuple: baseTuple,
     fetchChildren: async (parentObject, relation) => {
-      // Return child object IDs linked to parentObject via relation
-      const rows = await db.select({ subject: zanzoTuples.subject })
+      const rows = await db.select({ object: zanzoTuples.object })
         .from(zanzoTuples)
         .where(and(
           eq(zanzoTuples.subject, parentObject),
@@ -95,11 +95,48 @@ async function grantAccess(userId: string, projectId: string) {
     },
   });
 
-  // Insert base tuple + all derived tuples atomically
   await db.insert(zanzoTuples).values([baseTuple, ...derived]);
 }
 ```
 
-## Documentation
+### Revoking access with collapseTuples
 
-For full architecture details, refer to the [ZanzoJS Monorepo](https://github.com/GonzaloJeria/zanzo).
+`collapseTuples` is the symmetric inverse of `expandTuples`. It identifies all derived tuples to delete.
+```typescript
+import { collapseTuples } from '@zanzojs/core';
+
+async function revokeAccess(userId: string, relation: string, objectId: string) {
+  const baseTuple = {
+    subject: `User:${userId}`,
+    relation,
+    object: objectId,
+  };
+
+  const derived = await collapseTuples({
+    schema: engine.getSchema(),
+    revokedTuple: baseTuple,
+    fetchChildren: async (parentObject, relation) => {
+      const rows = await db.select({ object: zanzoTuples.object })
+        .from(zanzoTuples)
+        .where(and(
+          eq(zanzoTuples.subject, parentObject),
+          eq(zanzoTuples.relation, relation),
+        ));
+      return rows.map(r => r.object);
+    },
+  });
+
+  for (const tuple of [baseTuple, ...derived]) {
+    await db.delete(zanzoTuples).where(and(
+      eq(zanzoTuples.subject, tuple.subject),
+      eq(zanzoTuples.relation, tuple.relation),
+      eq(zanzoTuples.object, tuple.object),
+    ));
+  }
+}
+```
+
+> **expandTuples and collapseTuples are symmetric.** If `expandTuples` derived a tuple, `collapseTuples` will identify it for deletion. This guarantees no orphaned tuples.
+
+## Documentation
+For full architecture details, see the [ZanzoJS Monorepo](https://github.com/GonzaloJeria/zanzo).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zanzojs/drizzle",
-  "version": "0.1.0-beta.2",
+  "version": "0.2.0",
   "description": "Drizzle ORM adapter for Zanzo ReBAC. Zero-config Zanzibar Tuple Pattern with parameterized SQL.",
   "keywords": [
     "@zanzojs/core",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@zanzojs/core": "^0.1.0-beta.0",
+    "@zanzojs/core": "^0.2.0",
     "drizzle-orm": ">=0.29.0"
   },
   "devDependencies": {
@@ -46,7 +46,7 @@
     "typescript": "^5.7.2",
     "tsup": "latest",
     "vitest": "latest",
-    "@zanzojs/core": "0.1.0-beta.2"
+    "@zanzojs/core": "0.2.0"
   },
   "scripts": {
     "build": "tsup",