Read - Unified Read Pipeline

The unified read configuration that owns collection reads, single-record reads, and named view projections. Replaces crud.list and crud.get.

The read block owns the read side of every resource: the collection-level GET / endpoint, single-record GET /:id, and named view projections. It replaces the legacy crud.list and crud.get shapes — those are rejected at compile time in DSL v2.

Basic Usage

// features/customers/customers.ts
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { defineTable } from '@quickback/compiler';

export const customers = sqliteTable('customers', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull(),
  ssn: text('ssn'),
  status: text('status').notNull(),
  organizationId: text('organization_id').notNull(),
});

export default defineTable(customers, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  masking: {
    ssn: { type: 'ssn', show: { roles: ['admin'] } },
  },
  read: {
    access: { roles: ['member', 'admin'] },
    views: {
      summary: {
        fields: ['id', 'name', 'status'],
        access: { roles: ['member', 'admin'] },
      },
      full: {
        fields: ['id', 'name', 'email', 'ssn', 'status'],
        access: { roles: ['admin'] },
      },
    },
  },
  crud: {
    create: { access: { roles: ['admin'] } },
    update: { access: { roles: ['admin'] } },
    delete: { access: { roles: ['admin'] }, mode: 'soft' },
  },
});

What `read` Owns

Endpoint	Gate
`GET /api/v1/{resource}`	`read.access`
`GET /api/v1/{resource}/:id`	`read.access`
`GET /api/v1/{resource}?view={name}`	`read.views[name].access` (falls back to `read.access`)
`GET /api/v1/{resource}/views/{name}`	Same — explicit path form of the `?view=` dispatch

Single-record GET /:id inherits read.access automatically — there's no separate read.get block. If you need different access for single records, use record-level conditions on read.access:

read: {
  access: {
    or: [
      { roles: ['admin'] },
      { roles: ['member'], record: { ownerId: { equals: '$ctx.userId' } } },
    ],
  },
}

Configuration Options

interface ReadConfig {
  // Role/condition gate for collection reads, single-record reads, and the
  // default view fallback.
  access?: Access;

  // Optional read-side firewall override. If omitted, the resource-level
  // `firewall` block is used (the common case).
  firewall?: FirewallConfig;

  // Pagination defaults for collection reads.
  pageSize?: number;       // Default page size (default: 50)
  maxPageSize?: number;    // Hard cap (default: 100)

  // Named field projections. Each view has its own access and field list.
  views?: {
    [viewName: string]: ViewConfig;
  };
}

interface ViewConfig {
  fields: string[];        // Columns returned by this view
  access?: Access;         // Per-view access (falls back to read.access)
  pageSize?: number;
  maxPageSize?: number;
}

Access Ordering on `/:id`

Single-record GET /:id evaluates checks in this order to close the 404-vs-403 ID-probe channel:

Auth gate — 401 if unauthenticated
Pre-record access — role-only check (skips access.record predicates)
Firewall query — WHERE clause filters by ownership
Post-record access — full check including record-level predicates
Masking — applied to the response

An unauthorized caller without a matching role gets 403 from step 2 before the database is touched, so they can't distinguish "row exists in another tenant" from "row doesn't exist." A caller with the right role but the wrong tenant gets the firewall's configured response (403 by default; see firewallErrorMode: 'hide' for an opaque 404 instead).

Function-form access is opaque to the pre-check (it always passes there) and is fully evaluated post-record, so access: async (ctx, record) => ... still works as before.

Views Under `read.views`

Views are named field projections — Column Level Security. They live under read.views (not at the resource top level). See Views for the full feature reference.

read: {
  access: { roles: ['member', 'admin'] },
  views: {
    public: {
      fields: ['id', 'title', 'status'],
      access: { roles: ['PUBLIC'] },
    },
    internal: {
      fields: ['id', 'title', 'status', 'salaryMin', 'salaryMax'],
      access: { roles: ['admin'] },
    },
  },
}

Both endpoint shapes are emitted automatically:

Query-string dispatch: GET /api/v1/jobs?view=internal
Explicit path: GET /api/v1/jobs/views/internal

Migrating from `crud.list` / `crud.get`

DSL v2 rejects both at compile time. The migration is mechanical:

Before (DSL v1)	After (DSL v2)
`crud.list.access`	`read.access`
`crud.list.pageSize`	`read.pageSize`
`crud.list.maxPageSize`	`read.maxPageSize`
`crud.list.fields: [...]`	Move to a named view under `read.views`
`crud.get.access`	`read.access` (or record-level conditions)
`crud.get.fields: [...]`	Move to a named view; clients call `?view=...`
Top-level `views: {...}`	`read.views: {...}`

Example before/after:

// Before — DSL v1
crud: {
  list: {
    access: { roles: ['member'] },
    pageSize: 25,
  },
  get: {
    access: { roles: ['member'] },
    fields: ['id', 'name', 'status'],   // per-field projection
  },
  create: { access: { roles: ['admin'] } },
}

// After — DSL v2
read: {
  access: { roles: ['member'] },
  pageSize: 25,
  views: {
    summary: {
      fields: ['id', 'name', 'status'],
      access: { roles: ['member'] },
    },
  },
}
crud: {
  create: { access: { roles: ['admin'] } },
}

Clients that previously hit GET /:id to retrieve only summary fields now call GET /:id?view=summary.

Read-Only Resources

A resource that exposes only reads is valid with an empty crud block (or no crud block at all):

export default defineTable(balanceSnapshots, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  read: { access: { roles: ['member', 'admin'] } },
  // no crud — no writes
});