ignotum 0.0.6 → 0.0.8

package/src/dev-runtime/database.ts

@@ -11,8 +11,27 @@ import {
   dependencyKey,
   documentDependency,
   tableDependency,
-  type DependencyKey,
+  indexPointInvalidation,
+  indexRangeDependency,
+  type ReadDependency,
+  type WriteInvalidation,
 } from "@ignotum/contracts/runtime/hosted";
+import {
+  encodeIndexKey,
+  encodeIndexRange,
+  EncodedIndexKey,
+  IndexScalarValue,
+  indexIdentity,
+  successorIndexPrefix,
+  type IndexScalar,
+} from "@ignotum/contracts/runtime/index";
+import {
+  decodePaginationCursor,
+  encodePaginationCursor,
+  paginationQueryIdentity,
+  type PaginationOptions,
+  type PaginationPage,
+} from "@ignotum/contracts/runtime/pagination";
 import {
   documentNotFound,
   resultFromEffect,
@@ -23,7 +42,12 @@ import type {
   RuntimeSchemaDefinition,
   RuntimeTableDefinition,
 } from "@ignotum/contracts/runtime/schema";
-import { SchemaDefinitionTypeId } from "@ignotum/contracts/schema";
+import {
+  getValueDescriptor,
+  SchemaDefinitionTypeId,
+  type ValueDescriptor,
+} from "@ignotum/contracts/schema";
+import type { FileValue } from "@ignotum/contracts/schema/file";
 
 import { DevelopmentDatabase } from "./migrations.js";
 
@@ -36,6 +60,7 @@ type RuntimeDocumentValue =
   | number
   | string
   | Date
+  | FileValue
   | ReadonlyArray<RuntimeDocumentValue>
   | RuntimeObject;
 type RuntimeValue = RuntimeObject;
@@ -47,19 +72,46 @@ export interface RuntimeDocument {
   readonly updatedAt: Date;
 }
 
+interface LocalIndexRange {
+  readonly eq: (field: string, value: RuntimeDocumentValue) => LocalIndexRange;
+  readonly gt: (field: string, value: RuntimeDocumentValue) => LocalIndexRange;
+  readonly gte: (field: string, value: RuntimeDocumentValue) => LocalIndexRange;
+  readonly lt: (field: string, value: RuntimeDocumentValue) => LocalIndexRange;
+  readonly lte: (field: string, value: RuntimeDocumentValue) => LocalIndexRange;
+}
+
+interface LocalDatabaseQuery {
+  readonly index: (
+    name: string,
+    range?: (builder: LocalIndexRange) => LocalIndexRange,
+  ) => LocalDatabaseQuery;
+  readonly order: (direction: "asc" | "desc") => LocalDatabaseQuery;
+  readonly collect: () => Result<ReadonlyArray<RuntimeDocument>, never>;
+  readonly take: (count: number) => Result<ReadonlyArray<RuntimeDocument>, never>;
+  readonly first: () => Result<RuntimeDocument | undefined, never>;
+  readonly unique: () => Result<RuntimeDocument | undefined, never>;
+  readonly paginate: (options: PaginationOptions) => Result<PaginationPage<RuntimeDocument>, never>;
+}
+
 export interface LocalDatabaseReader {
   readonly find: (tableName: string, id: string) => Result<RuntimeDocument | undefined, never>;
   readonly get: (tableName: string, id: string) => Result<RuntimeDocument, DocumentNotFoundValue>;
-  readonly query: (tableName: string) => {
-    readonly collect: () => Result<ReadonlyArray<RuntimeDocument>, never>;
-  };
+  readonly query: (tableName: string) => LocalDatabaseQuery;
 }
 
 export interface LocalDatabaseWriter extends LocalDatabaseReader {
-  readonly delete: (tableName: string, id: string) => Result<void, never>;
+  readonly delete: (tableName: string, id: string) => Result<void, DocumentNotFoundValue>;
   readonly insert: (tableName: string, value: RuntimeValue) => Result<GeneratedIdType, never>;
-  readonly patch: (tableName: string, id: string, value: RuntimeValue) => Result<void, never>;
-  readonly replace: (tableName: string, id: string, value: RuntimeValue) => Result<void, never>;
+  readonly patch: (
+    tableName: string,
+    id: string,
+    value: RuntimeValue,
+  ) => Result<void, DocumentNotFoundValue>;
+  readonly replace: (
+    tableName: string,
+    id: string,
+    value: RuntimeValue,
+  ) => Result<void, DocumentNotFoundValue>;
 }
 
 export interface LocalQueryContext {
@@ -82,7 +134,7 @@ interface LocalDatabaseService {
   ) => Effect.Effect<
     {
       readonly value: Success;
-      readonly dependencies: ReadonlyArray<DependencyKey>;
+      readonly dependencies: ReadonlyArray<ReadDependency>;
       readonly observedRevision: AppStateRevision;
     },
     Failure | SqlError.SqlError
@@ -97,7 +149,7 @@ interface LocalDatabaseService {
   ) => Effect.Effect<
     {
       readonly value: Success;
-      readonly invalidations: ReadonlyArray<DependencyKey>;
+      readonly invalidations: ReadonlyArray<WriteInvalidation>;
       readonly committedRevision: AppStateRevision;
     },
     Failure | SqlError.SqlError
@@ -111,6 +163,15 @@ const StoredDocument = Schema.Struct({
   fields: Schema.String,
 });
 type StoredDocument = typeof StoredDocument.Type;
+const IndexedStoredDocument = Schema.Struct({ ...StoredDocument.fields, key: Schema.String });
+type IndexedStoredDocument = typeof IndexedStoredDocument.Type;
+const StoredIndex = Schema.Struct({
+  id: Schema.Natural,
+  identity: Schema.String,
+  name: Schema.String,
+  fields: Schema.String,
+});
+type StoredIndex = typeof StoredIndex.Type;
 
 const StoredTable = Schema.Struct({ id: TableId, name: Schema.String });
 type StoredTable = typeof StoredTable.Type;
@@ -128,13 +189,20 @@ const TableInsert = Schema.Struct({ id: TableId, name: Schema.String });
 const RevisionRow = Schema.Struct({ revision: AppStateRevision });
 type DatabaseOperation = "collect" | "get" | "insert" | "patch" | "replace";
 
-interface DependencyRecorder {
-  readonly record: (...dependencies: ReadonlyArray<DependencyKey>) => void;
-  readonly values: () => ReadonlyArray<DependencyKey>;
+interface ResolvedIndex extends StoredIndex {
+  readonly definition: { readonly name: string; readonly fields: readonly string[] };
+  readonly descriptors: ReadonlyArray<ValueDescriptor>;
+}
+
+interface DependencyRecorder<Dependency extends ReadDependency | WriteInvalidation> {
+  readonly record: (...dependencies: ReadonlyArray<Dependency>) => void;
+  readonly values: () => ReadonlyArray<Dependency>;
 }
 
-const makeDependencyRecorder = (): DependencyRecorder => {
-  const dependencies = new Map<string, DependencyKey>();
+const makeDependencyRecorder = <
+  Dependency extends ReadDependency | WriteInvalidation,
+>(): DependencyRecorder<Dependency> => {
+  const dependencies = new Map<string, Dependency>();
   return {
     record: (...added) => {
       for (const dependency of added) dependencies.set(dependencyKey(dependency), dependency);
@@ -240,6 +308,25 @@ const toRuntimeDocument = Effect.fn("LocalDatabase.toRuntimeDocument")(function*
 const nextUpdatedAt = (now: DateTime.DateTime, previous: number): number =>
   Math.max(DateTime.toEpochMillis(now), previous + 1);
 
+const decodeIndexScalar = Schema.decodeUnknownSync(IndexScalarValue);
+
+const indexDescriptors = (
+  table: RuntimeTableDefinition,
+  fields: ReadonlyArray<string>,
+): ReadonlyArray<ValueDescriptor> =>
+  fields.map((field) => {
+    const schema = table.fields[field];
+    const descriptor = schema === undefined ? undefined : getValueDescriptor(schema);
+    if (descriptor === undefined) throw new Error(`Index field '${field}' has no descriptor.`);
+    return descriptor;
+  });
+
+const storedIndexKey = (index: ResolvedIndex, row: StoredDocument): EncodedIndexKey => {
+  const fields = Schema.decodeSync(Schema.fromJsonString(Schema.JsonObject))(row.fields);
+  const values = index.definition.fields.map((field) => decodeIndexScalar(fields[field]));
+  return encodeIndexKey(index.descriptors, values, row.createdAt, row.id);
+};
+
 export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseService>()(
   "ignotum/dev-runtime/database/LocalDatabase",
 ) {
@@ -291,6 +378,31 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
           ORDER BY createdAt ASC, id ASC
         `,
       });
+      const listIndexes = SqlSchema.findAll({
+        Request: TableLookup,
+        Result: StoredIndex,
+        execute: ({ tableId }) => sql`
+          SELECT id, identity, name, fields
+          FROM indexes
+          WHERE tableId = ${tableId}
+          ORDER BY id ASC
+        `,
+      });
+      const insertIndex = SqlSchema.findOne({
+        Request: Schema.Struct({
+          tableId: TableId,
+          identity: Schema.String,
+          name: Schema.String,
+          fields: Schema.String,
+        }),
+        Result: StoredIndex,
+        execute: ({ tableId, identity, name, fields }) => sql`
+          INSERT INTO indexes (tableId, identity, name, fields)
+          VALUES (${tableId}, ${identity}, ${name}, ${fields})
+          ON CONFLICT (identity) DO UPDATE SET identity = excluded.identity
+          RETURNING id, identity, name, fields
+        `,
+      });
       const currentRevision = SqlSchema.findOne({
         Request: Schema.Void,
         Result: RevisionRow,
@@ -324,11 +436,96 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
         return { ...stored, definition };
       });
 
+      const resolvedIndexes = Effect.fn("LocalDatabase.resolvedIndexes")(function* (
+        table: ResolvedTable,
+      ) {
+        const stored = yield* listIndexes({ tableId: table.id });
+        return Object.values(table.definition.indexes).map((definition) => {
+          const identity = indexIdentity(table.id, definition.name, definition.fields);
+          const row = stored.find((candidate) => candidate.identity === identity);
+          if (row === undefined) throw new Error(`Index '${definition.name}' is not prepared.`);
+          return {
+            ...row,
+            definition,
+            descriptors: indexDescriptors(table.definition, definition.fields),
+          } satisfies ResolvedIndex;
+        });
+      });
+
+      const prepareIndexes = Effect.fn("LocalDatabase.prepareIndexes")(function* (
+        schema: RuntimeSchemaDefinition,
+      ) {
+        for (const [tableName, definition] of Object.entries(schema[SchemaDefinitionTypeId])) {
+          const table = yield* resolveTable(schema, tableName);
+          const stored = yield* listIndexes({ tableId: table.id });
+          const expected = new Set<string>();
+          for (const index of Object.values(definition.indexes)) {
+            const identity = indexIdentity(table.id, index.name, index.fields);
+            expected.add(identity);
+            if (stored.some((candidate) => candidate.identity === identity)) continue;
+            const fields = JSON.stringify(index.fields);
+            const created = yield* insertIndex({
+              tableId: table.id,
+              identity,
+              name: index.name,
+              fields,
+            }).pipe(Effect.catchTags({ NoSuchElementError: Effect.die }));
+            const resolved: ResolvedIndex = {
+              ...created,
+              definition: index,
+              descriptors: indexDescriptors(definition, index.fields),
+            };
+            const documents = yield* collectStored({ tableId: table.id });
+            yield* Effect.forEach(
+              documents,
+              (document) =>
+                sql`
+                INSERT INTO indexEntries (indexId, tableId, documentId, key)
+                VALUES (${resolved.id}, ${table.id}, ${document.id}, ${storedIndexKey(resolved, document)})
+              `,
+            );
+          }
+          yield* Effect.forEach(
+            stored.filter((index) => !expected.has(index.identity)),
+            (index) => sql`DELETE FROM indexes WHERE id = ${index.id}`,
+          );
+        }
+      });
+
+      const indexKeys = Effect.fn("LocalDatabase.indexKeys")(function* (
+        table: ResolvedTable,
+        row: StoredDocument,
+      ) {
+        const indexes = yield* resolvedIndexes(table);
+        return indexes.map((index) => ({
+          index,
+          key: storedIndexKey(index, row),
+          identity: indexIdentity(table.id, index.name, index.definition.fields),
+        }));
+      });
+
+      const writeIndexEntries = Effect.fn("LocalDatabase.writeIndexEntries")(function* (
+        table: ResolvedTable,
+        row: StoredDocument,
+      ) {
+        const keys = yield* indexKeys(table, row);
+        yield* Effect.forEach(
+          keys,
+          ({ index, key }) =>
+            sql`
+            INSERT INTO indexEntries (indexId, tableId, documentId, key)
+            VALUES (${index.id}, ${table.id}, ${row.id}, ${key})
+            ON CONFLICT (indexId, documentId) DO UPDATE SET key = excluded.key
+          `,
+        );
+        return keys;
+      });
+
       const find = Effect.fn("LocalDatabase.find")(function* (
         schema: RuntimeSchemaDefinition,
         tableName: string,
         id: string,
-        dependencies?: DependencyRecorder,
+        dependencies?: DependencyRecorder<ReadDependency>,
       ) {
         const table = yield* resolveTable(schema, tableName);
         const documentId = GeneratedId.make(id);
@@ -338,24 +535,178 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
         return yield* toRuntimeDocument(table.definition, tableName, row.value, "get");
       });
 
-      const collect = Effect.fn("LocalDatabase.collect")(function* (
+      const queryDocuments = Effect.fn("LocalDatabase.queryDocuments")(function* (
         schema: RuntimeSchemaDefinition,
         tableName: string,
-        dependencies?: DependencyRecorder,
+        selectedIndex: string | undefined,
+        bounds: { readonly lower?: EncodedIndexKey; readonly upper?: EncodedIndexKey },
+        order: "Asc" | "Desc",
+        limit: number | undefined,
+        pagination: PaginationOptions | undefined,
+        dependencies?: DependencyRecorder<ReadDependency>,
       ) {
         const table = yield* resolveTable(schema, tableName);
-        dependencies?.record(tableDependency(table.id));
-        const rows = yield* collectStored({ tableId: table.id });
-        return yield* Effect.forEach(rows, (row) =>
+        if (selectedIndex === undefined) {
+          dependencies?.record(tableDependency(table.id));
+          const queryIdentity = paginationQueryIdentity(
+            table.id,
+            null,
+            undefined,
+            undefined,
+            order,
+          );
+          const decodedCursor =
+            pagination?.cursor === null || pagination === undefined
+              ? undefined
+              : decodePaginationCursor(pagination.cursor);
+          if (decodedCursor !== undefined && decodedCursor.query !== queryIdentity) {
+            throw new Error("A pagination cursor belongs to another query.");
+          }
+          const cursor = decodedCursor?.position;
+          if (cursor !== undefined && cursor.type !== "Table") {
+            throw new Error("A pagination cursor has the wrong position type.");
+          }
+          const clauses = ["tableId = ?"];
+          const parameters: Array<number | string> = [table.id];
+          if (cursor !== undefined) {
+            const operator = order === "Asc" ? ">" : "<";
+            clauses.push(`(createdAt ${operator} ? OR (createdAt = ? AND id ${operator} ?))`);
+            parameters.push(cursor.createdAt, cursor.createdAt, cursor.id);
+          }
+          const storageLimit = pagination === undefined ? limit : pagination.pageSize + 1;
+          if (storageLimit !== undefined) parameters.push(storageLimit);
+          const rows = yield* sql.unsafe<StoredDocument>(
+            `SELECT id, createdAt, updatedAt, fields
+             FROM documents
+             WHERE ${clauses.join(" AND ")}
+             ORDER BY createdAt ${order === "Asc" ? "ASC" : "DESC"}, id ${order === "Asc" ? "ASC" : "DESC"}${storageLimit === undefined ? "" : " LIMIT ?"}`,
+            parameters,
+          );
+          const decoded = yield* Schema.decodeUnknownEffect(Schema.Array(StoredDocument))(rows);
+          const hasMore = pagination !== undefined && decoded.length > pagination.pageSize;
+          const pageRows =
+            pagination === undefined ? decoded : decoded.slice(0, pagination.pageSize);
+          const documents = yield* Effect.forEach(pageRows, (row) =>
+            toRuntimeDocument(table.definition, tableName, row, "collect"),
+          );
+          const last = pageRows.at(-1);
+          const nextCursor =
+            !hasMore || last === undefined
+              ? null
+              : encodePaginationCursor(queryIdentity, {
+                  type: "Table",
+                  createdAt: last.createdAt,
+                  id: last.id,
+                });
+          return { documents, nextCursor };
+        }
+
+        const indexes = yield* resolvedIndexes(table);
+        const index = indexes.find((candidate) => candidate.name === selectedIndex);
+        if (index === undefined) throw new Error(`Unknown index '${selectedIndex}'.`);
+        const identity = indexIdentity(table.id, index.name, index.definition.fields);
+        const queryIdentity = paginationQueryIdentity(
+          table.id,
+          identity,
+          bounds.lower,
+          bounds.upper,
+          order,
+        );
+        const decodedCursor =
+          pagination?.cursor === null || pagination === undefined
+            ? undefined
+            : decodePaginationCursor(pagination.cursor);
+        if (decodedCursor !== undefined && decodedCursor.query !== queryIdentity) {
+          throw new Error("A pagination cursor belongs to another query.");
+        }
+        const cursor = decodedCursor?.position;
+        if (cursor !== undefined && cursor.type !== "Index") {
+          throw new Error("A pagination cursor has the wrong position type.");
+        }
+        const cursorLower =
+          cursor !== undefined && order === "Asc" ? successorIndexPrefix(cursor.key) : undefined;
+        const cursorUpper = cursor !== undefined && order === "Desc" ? cursor.key : undefined;
+        const effectiveBounds = {
+          lower:
+            bounds.lower === undefined
+              ? cursorLower
+              : cursorLower === undefined || bounds.lower > cursorLower
+                ? bounds.lower
+                : cursorLower,
+          upper:
+            bounds.upper === undefined
+              ? cursorUpper
+              : cursorUpper === undefined || bounds.upper < cursorUpper
+                ? bounds.upper
+                : cursorUpper,
+        };
+        const clauses = ["entries.indexId = ?"];
+        const parameters: Array<number | string> = [index.id];
+        if (effectiveBounds.lower !== undefined) {
+          clauses.push("entries.key >= ?");
+          parameters.push(effectiveBounds.lower);
+        }
+        if (effectiveBounds.upper !== undefined) {
+          clauses.push("entries.key < ?");
+          parameters.push(effectiveBounds.upper);
+        }
+        const storageLimit = pagination === undefined ? limit : pagination.pageSize + 1;
+        if (storageLimit !== undefined) parameters.push(storageLimit);
+        const rows = yield* sql.unsafe<IndexedStoredDocument>(
+          `SELECT documents.id, documents.createdAt, documents.updatedAt, documents.fields,
+                  entries.key
+           FROM indexEntries AS entries
+           JOIN documents
+             ON documents.tableId = entries.tableId
+            AND documents.id = entries.documentId
+           WHERE ${clauses.join(" AND ")}
+           ORDER BY entries.key ${order === "Asc" ? "ASC" : "DESC"}${storageLimit === undefined ? "" : " LIMIT ?"}`,
+          parameters,
+        );
+        const decoded = yield* Schema.decodeUnknownEffect(Schema.Array(IndexedStoredDocument))(
+          rows,
+        );
+        const hasMore = pagination !== undefined && decoded.length > pagination.pageSize;
+        const pageRows = pagination === undefined ? decoded : decoded.slice(0, pagination.pageSize);
+        let dependencyBounds = effectiveBounds;
+        const shouldCrop =
+          pagination === undefined
+            ? limit !== undefined && limit > 0 && decoded.length === limit
+            : hasMore;
+        if (shouldCrop) {
+          const last = pageRows.at(-1);
+          if (last !== undefined) {
+            dependencyBounds =
+              order === "Asc"
+                ? {
+                    ...effectiveBounds,
+                    upper: successorIndexPrefix(EncodedIndexKey.make(last.key)),
+                  }
+                : { ...effectiveBounds, lower: EncodedIndexKey.make(last.key) };
+          }
+        }
+        dependencies?.record(
+          indexRangeDependency(table.id, identity, dependencyBounds.lower, dependencyBounds.upper),
+        );
+        const documents = yield* Effect.forEach(pageRows, (row) =>
           toRuntimeDocument(table.definition, tableName, row, "collect"),
         );
+        const last = pageRows.at(-1);
+        const nextCursor =
+          !hasMore || last === undefined
+            ? null
+            : encodePaginationCursor(queryIdentity, {
+                type: "Index",
+                key: EncodedIndexKey.make(last.key),
+              });
+        return { documents, nextCursor };
       });
 
       const insert = Effect.fn("LocalDatabase.insert")(function* (
         schema: RuntimeSchemaDefinition,
         tableName: string,
         value: RuntimeValue,
-        invalidations: DependencyRecorder,
+        invalidations: DependencyRecorder<WriteInvalidation>,
       ) {
         const table = yield* resolveTable(schema, tableName);
         const fields = yield* encodeFields(table.definition, tableName, value, "insert", null);
@@ -365,7 +716,13 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
           INSERT INTO documents (id, tableId, createdAt, updatedAt, fields)
           VALUES (${id}, ${table.id}, ${now}, ${now}, ${fields})
         `;
-        invalidations.record(tableDependency(table.id), documentDependency(table.id, id));
+        const row = { id, createdAt: now, updatedAt: now, fields } satisfies StoredDocument;
+        const keys = yield* writeIndexEntries(table, row);
+        invalidations.record(
+          tableDependency(table.id),
+          documentDependency(table.id, id),
+          ...keys.map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)),
+        );
         return id;
       });
 
@@ -373,12 +730,21 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
         schema: RuntimeSchemaDefinition,
         tableName: string,
         id: string,
-        invalidations: DependencyRecorder,
+        invalidations: DependencyRecorder<WriteInvalidation>,
       ) {
-        const table = yield* resolveTable(schema, tableName);
+        const table = yield* resolveTable(schema, tableName).pipe(Effect.orDie);
         const documentId = GeneratedId.make(id);
-        yield* sql`DELETE FROM documents WHERE id = ${id} AND tableId = ${table.id}`;
-        invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
+        const stored = yield* findStored({ id, tableId: table.id }).pipe(Effect.orDie);
+        if (Option.isNone(stored)) return yield* Effect.fail(documentNotFound(tableName, id));
+        const keys = yield* indexKeys(table, stored.value).pipe(Effect.orDie);
+        yield* sql`DELETE FROM documents WHERE id = ${id} AND tableId = ${table.id}`.pipe(
+          Effect.orDie,
+        );
+        invalidations.record(
+          tableDependency(table.id),
+          documentDependency(table.id, documentId),
+          ...keys.map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)),
+        );
       });
 
       const patch = Effect.fn("LocalDatabase.patch")(function* (
@@ -386,28 +752,44 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
         tableName: string,
         id: string,
         value: RuntimeValue,
-        invalidations: DependencyRecorder,
+        invalidations: DependencyRecorder<WriteInvalidation>,
       ) {
-        const table = yield* resolveTable(schema, tableName);
+        const table = yield* resolveTable(schema, tableName).pipe(Effect.orDie);
         const documentId = GeneratedId.make(id);
-        const stored = yield* findStored({ id, tableId: table.id });
-        if (Option.isSome(stored)) {
-          const current = yield* decodeFields(table.definition, tableName, stored.value, "patch");
-          const fields = yield* encodeFields(
-            table.definition,
-            tableName,
-            { ...current, ...value },
-            "patch",
-            id,
-          );
-          const updatedAt = nextUpdatedAt(yield* DateTime.now, stored.value.updatedAt);
-          yield* sql`
-            UPDATE documents
-            SET fields = ${fields}, updatedAt = ${updatedAt}
-            WHERE id = ${id} AND tableId = ${table.id}
-          `;
-        }
-        invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
+        const stored = yield* findStored({ id, tableId: table.id }).pipe(Effect.orDie);
+        if (Option.isNone(stored)) return yield* Effect.fail(documentNotFound(tableName, id));
+        const oldKeys = yield* indexKeys(table, stored.value).pipe(Effect.orDie);
+        const current = yield* decodeFields(
+          table.definition,
+          tableName,
+          stored.value,
+          "patch",
+        ).pipe(Effect.orDie);
+        const fields = yield* encodeFields(
+          table.definition,
+          tableName,
+          { ...current, ...value },
+          "patch",
+          id,
+        ).pipe(Effect.orDie);
+        const updatedAt = nextUpdatedAt(yield* DateTime.now, stored.value.updatedAt);
+        yield* sql`
+          UPDATE documents
+          SET fields = ${fields}, updatedAt = ${updatedAt}
+          WHERE id = ${id} AND tableId = ${table.id}
+        `.pipe(Effect.orDie);
+        const newKeys = yield* writeIndexEntries(table, {
+          ...stored.value,
+          fields,
+          updatedAt,
+        }).pipe(Effect.orDie);
+        invalidations.record(
+          tableDependency(table.id),
+          documentDependency(table.id, documentId),
+          ...[...oldKeys, ...newKeys].map(({ identity, key }) =>
+            indexPointInvalidation(table.id, identity, key),
+          ),
+        );
       });
 
       const replace = Effect.fn("LocalDatabase.replace")(function* (
@@ -415,28 +797,194 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
         tableName: string,
         id: string,
         value: RuntimeValue,
-        invalidations: DependencyRecorder,
+        invalidations: DependencyRecorder<WriteInvalidation>,
       ) {
-        const table = yield* resolveTable(schema, tableName);
+        const table = yield* resolveTable(schema, tableName).pipe(Effect.orDie);
         const documentId = GeneratedId.make(id);
-        const stored = yield* findStored({ id, tableId: table.id });
-        if (Option.isSome(stored)) {
-          const fields = yield* encodeFields(table.definition, tableName, value, "replace", id);
-          const updatedAt = nextUpdatedAt(yield* DateTime.now, stored.value.updatedAt);
-          yield* sql`
-            UPDATE documents
-            SET fields = ${fields}, updatedAt = ${updatedAt}
-            WHERE id = ${id} AND tableId = ${table.id}
-          `;
-        }
-        invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
+        const stored = yield* findStored({ id, tableId: table.id }).pipe(Effect.orDie);
+        if (Option.isNone(stored)) return yield* Effect.fail(documentNotFound(tableName, id));
+        const oldKeys = yield* indexKeys(table, stored.value).pipe(Effect.orDie);
+        const fields = yield* encodeFields(table.definition, tableName, value, "replace", id).pipe(
+          Effect.orDie,
+        );
+        const updatedAt = nextUpdatedAt(yield* DateTime.now, stored.value.updatedAt);
+        yield* sql`
+          UPDATE documents
+          SET fields = ${fields}, updatedAt = ${updatedAt}
+          WHERE id = ${id} AND tableId = ${table.id}
+        `.pipe(Effect.orDie);
+        const newKeys = yield* writeIndexEntries(table, {
+          ...stored.value,
+          fields,
+          updatedAt,
+        }).pipe(Effect.orDie);
+        invalidations.record(
+          tableDependency(table.id),
+          documentDependency(table.id, documentId),
+          ...[...oldKeys, ...newKeys].map(({ identity, key }) =>
+            indexPointInvalidation(table.id, identity, key),
+          ),
+        );
       });
 
       const makeReader = (
         schema: RuntimeSchemaDefinition,
-        dependencies?: DependencyRecorder,
-      ): LocalDatabaseReader =>
-        Object.freeze({
+        dependencies?: DependencyRecorder<ReadDependency>,
+      ): LocalDatabaseReader => {
+        const databaseQuery = (
+          tableName: string,
+          selectedIndex?: string,
+          selectedBounds: {
+            readonly lower?: EncodedIndexKey;
+            readonly upper?: EncodedIndexKey;
+          } = {},
+          order: "Asc" | "Desc" = "Asc",
+        ): LocalDatabaseQuery => {
+          const table = schema[SchemaDefinitionTypeId][tableName];
+          if (table === undefined) throw new Error(`Unknown database table '${tableName}'.`);
+          const run = (limit?: number) =>
+            queryDocuments(
+              schema,
+              tableName,
+              selectedIndex,
+              selectedBounds,
+              order,
+              limit,
+              undefined,
+              dependencies,
+            ).pipe(
+              Effect.map(({ documents }) => documents),
+              Effect.orDie,
+            );
+          const runPage = (pagination: PaginationOptions) =>
+            queryDocuments(
+              schema,
+              tableName,
+              selectedIndex,
+              selectedBounds,
+              order,
+              undefined,
+              pagination,
+              dependencies,
+            ).pipe(Effect.orDie);
+          const validateLimit = (count: number) => {
+            if (!Number.isInteger(count) || count < 0 || count > 1_000) {
+              throw new Error("Query limits must be integers between 0 and 1000.");
+            }
+            return count;
+          };
+          const result: LocalDatabaseQuery = {
+            index: (name, buildRange) => {
+              if (selectedIndex !== undefined)
+                throw new Error("A query can select only one index.");
+              const definition = table.indexes[name];
+              if (definition === undefined) {
+                throw new Error(`Unknown index '${name}' on table '${tableName}'.`);
+              }
+              if (buildRange === undefined) return databaseQuery(tableName, name, {}, order);
+              const fields = [...definition.fields, "createdAt", "id"];
+              const descriptors = [
+                ...indexDescriptors(table, definition.fields),
+                { type: "date" } as const,
+                { type: "id", table: tableName } as const,
+              ];
+              const equal: IndexScalar[] = [];
+              let lower: { value: IndexScalar; inclusive: boolean } | undefined;
+              let upper: { value: IndexScalar; inclusive: boolean } | undefined;
+              let position = 0;
+              const encodeValue = (field: string, value: RuntimeDocumentValue): IndexScalar => {
+                const codec =
+                  field === "createdAt"
+                    ? Schema.DateFromMillis
+                    : field === "id"
+                      ? GeneratedId
+                      : table.fields[field];
+                if (codec === undefined) throw new Error(`Unknown index field '${field}'.`);
+                // SAFETY: defineSchema only accepts service-free application field codecs.
+                return decodeIndexScalar(
+                  Schema.encodeUnknownSync(codec as Schema.Codec<unknown, unknown, never>)(value),
+                );
+              };
+              const expectField = (field: string) => {
+                const expected = fields[position];
+                if (field !== expected) {
+                  throw new Error(`Expected index field '${expected}', received '${field}'.`);
+                }
+              };
+              const builder: LocalIndexRange = {
+                eq: (field, value) => {
+                  if (lower !== undefined || upper !== undefined) {
+                    throw new Error("Equality cannot follow an index bound.");
+                  }
+                  expectField(field);
+                  equal.push(encodeValue(field, value));
+                  position += 1;
+                  return builder;
+                },
+                gt: (field, value) => {
+                  expectField(field);
+                  if (lower !== undefined) throw new Error("An index range has one lower bound.");
+                  lower = { value: encodeValue(field, value), inclusive: false };
+                  return builder;
+                },
+                gte: (field, value) => {
+                  expectField(field);
+                  if (lower !== undefined) throw new Error("An index range has one lower bound.");
+                  lower = { value: encodeValue(field, value), inclusive: true };
+                  return builder;
+                },
+                lt: (field, value) => {
+                  expectField(field);
+                  if (upper !== undefined) throw new Error("An index range has one upper bound.");
+                  upper = { value: encodeValue(field, value), inclusive: false };
+                  return builder;
+                },
+                lte: (field, value) => {
+                  expectField(field);
+                  if (upper !== undefined) throw new Error("An index range has one upper bound.");
+                  upper = { value: encodeValue(field, value), inclusive: true };
+                  return builder;
+                },
+              };
+              buildRange(builder);
+              return databaseQuery(
+                tableName,
+                name,
+                encodeIndexRange(descriptors, equal, lower, upper),
+                order,
+              );
+            },
+            order: (direction) =>
+              databaseQuery(
+                tableName,
+                selectedIndex,
+                selectedBounds,
+                direction === "asc" ? "Asc" : "Desc",
+              ),
+            collect: () => resultFromEffect(run()),
+            take: (count) => resultFromEffect(run(validateLimit(count))),
+            first: () => resultFromEffect(run(1).pipe(Effect.map((documents) => documents[0]))),
+            unique: () =>
+              resultFromEffect(
+                run(2).pipe(
+                  Effect.flatMap((documents) =>
+                    documents.length > 1
+                      ? Effect.die(new Error("A unique query matched more than one document."))
+                      : Effect.succeed(documents[0]),
+                  ),
+                ),
+              ),
+            paginate: (options) =>
+              resultFromEffect(
+                runPage(options).pipe(
+                  Effect.map(({ documents, nextCursor }) => ({ items: documents, nextCursor })),
+                ),
+              ),
+          };
+          return Object.freeze(result);
+        };
+
+        return Object.freeze({
           find: (tableName: string, id: string) =>
             resultFromEffect(find(schema, tableName, id, dependencies).pipe(Effect.orDie)),
           get: (tableName: string, id: string) =>
@@ -450,32 +998,25 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
                 ),
               ),
             ),
-          query: (tableName: string) =>
-            Object.freeze({
-              collect: () =>
-                resultFromEffect(collect(schema, tableName, dependencies).pipe(Effect.orDie)),
-            }),
+          query: (tableName: string) => databaseQuery(tableName),
         });
+      };
 
       const makeWriter = (
         schema: RuntimeSchemaDefinition,
-        invalidations: DependencyRecorder,
+        invalidations: DependencyRecorder<WriteInvalidation>,
       ): LocalDatabaseWriter => {
         const reader = makeReader(schema);
         return Object.freeze({
           ...reader,
           delete: (tableName: string, id: string) =>
-            resultFromEffect(
-              deleteDocument(schema, tableName, id, invalidations).pipe(Effect.orDie),
-            ),
+            resultFromEffect(deleteDocument(schema, tableName, id, invalidations)),
           insert: (tableName: string, value: RuntimeValue) =>
             resultFromEffect(insert(schema, tableName, value, invalidations).pipe(Effect.orDie)),
           patch: (tableName: string, id: string, value: RuntimeValue) =>
-            resultFromEffect(patch(schema, tableName, id, value, invalidations).pipe(Effect.orDie)),
+            resultFromEffect(patch(schema, tableName, id, value, invalidations)),
           replace: (tableName: string, id: string, value: RuntimeValue) =>
-            resultFromEffect(
-              replace(schema, tableName, id, value, invalidations).pipe(Effect.orDie),
-            ),
+            resultFromEffect(replace(schema, tableName, id, value, invalidations)),
         });
       };
 
@@ -485,7 +1026,8 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
       ) =>
         sql.withTransaction(
           Effect.gen(function* () {
-            const dependencies = makeDependencyRecorder();
+            yield* prepareIndexes(schema).pipe(Effect.orDie);
+            const dependencies = makeDependencyRecorder<ReadDependency>();
             const context = Object.freeze({
               db: makeReader(schema, dependencies),
             });
@@ -502,7 +1044,8 @@ export class LocalDatabase extends Context.Service<LocalDatabase, LocalDatabaseS
       ) =>
         sql.withTransaction(
           Effect.gen(function* () {
-            const invalidations = makeDependencyRecorder();
+            yield* prepareIndexes(schema).pipe(Effect.orDie);
+            const invalidations = makeDependencyRecorder<WriteInvalidation>();
             const context = Object.freeze({
               db: makeWriter(schema, invalidations),
             });