From b726d29035e416b0d7bdfa959e6120819fa3bcf1 Mon Sep 17 00:00:00 2001
From: Antony Rizzitelli <rizzitelli.antony@pm.me>
Date: Sun, 8 Nov 2026 05:57:16 +0000
Subject: [PATCH] docs(schema): state that a refused registration fails the
 schema's queries

---
 src/schema.ts | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/schema.ts b/src/schema.ts
index ff34b36..41b374d 100644
--- a/src/schema.ts
+++ b/src/schema.ts
@@ -5,7 +5,16 @@ import {
   type SchemaDefinition,
 } from "./staged-query/schema";
 
-/** @internal */
+/**
+ * Registers each schema a consumer defines with the bound database module.
+ *
+ * The register handler runs when the schema is defined, and on attach for the
+ * schemas defined before it. Its return value is discarded, so it must not
+ * throw or return a promise that rejects. A module that refuses a definition
+ * keeps the refusal and rejects every query on the schema with its message.
+ *
+ * @internal
+ */
 export const Schemas = new RegisteringProxy<
   (name: string, def: SchemaDefinition) => void
 >();
@@ -23,6 +32,17 @@ export class Schema<T = any> extends StagedSchema<T, SchemaDefinition> {
     return Schema.defined;
   }
 
+  /**
+   * Defines a schema with the given ID and registers it with the bound
+   * database module.
+   *
+   * Registration never throws or rejects. When the module refuses the
+   * definition, every query on the schema, `createInstance()` included,
+   * rejects with the module's message.
+   *
+   * @param id ID of this schema, changing this will leave previous data inaccessible
+   * @param definition Schema definition (tables, fields, indexes..)
+   */
   public constructor(id: string, definition: SchemaDefinition) {
     super(id, definition);
     Schema.defined.set(id, this);