@zanzojs/drizzle

The official Drizzle ORM adapter for ZanzoJS.

When to use this package

@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.

// 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.

Installation

pnpm add @zanzojs/core @zanzojs/drizzle drizzle-orm

Setup

1. Create the Universal Tuple Table

All relationships live in a single table. This is the Zanzibar pattern.

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';

export const zanzoTuples = sqliteTable('zanzo_tuples', {
  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. Create the adapter

import { createZanzoAdapter } from '@zanzojs/drizzle';
import { engine } from './zanzo.config';
import { zanzoTuples } from './schema';

export const withPermissions = createZanzoAdapter(engine, zanzoTuples);

3. Query pushdown

async function getReadableDocuments(userId: string) {
  return await db.select()
    .from(documents)
    .where(withPermissions(`User:${userId}`, 'read', 'Document', documents.id));
}

Write Operations

Granting access with expandTuples

When assigning a role that involves nested permission paths, use expandTuples to materialize all derived tuples atomically.

import { expandTuples } from '@zanzojs/core';

async function grantAccess(userId: string, relation: string, objectId: string) {
  const baseTuple = {
    subject: `User:${userId}`,
    relation,
    object: objectId,
  };

  const derived = await expandTuples({
    schema: engine.getSchema(),
    newTuple: 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);
    },
  });

  await db.insert(zanzoTuples).values([baseTuple, ...derived]);
}

Revoking access with collapseTuples

collapseTuples is the symmetric inverse of expandTuples. It identifies all derived tuples to delete.

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.