@noormdev/sdk 1.0.2 → 1.1.0

package/README.md

@@ -71,6 +71,29 @@ await ctx.proc('refresh_cache');
 `createContext<DB, Procs, Funcs, Tvfs>` takes a map per routine kind. Plain `void` is shorthand for "no arguments, no meaningful return".
 
 
+## Schema scoping
+
+`ctx.withSchema<SDB>(name)` derives a `Context` scoped to one schema — same connection, pool, and lifecycle as the parent, just qualified generics and query builder.
+
+```typescript
+const acct = ctx.withSchema<AcctDB>('accounting');
+
+const invoices = await acct.kysely.selectFrom('invoices').selectAll().execute();
+// select * from "accounting"."invoices" — typed against AcctDB
+
+await acct.proc('rebuild_ledger', { year: 2026 });
+// CALL "accounting"."rebuild_ledger"("year" => $1)
+
+await ctx.kysely.selectFrom('users').execute(); // parent untouched, no prefix
+
+await ctx.disconnect(); // one lifecycle closes both
+```
+
+Calling `withSchema` again replaces the schema instead of stacking it, and a `proc`/`func`/`tvf` name that already contains a `.` passes through unqualified. Raw `` sql`…` `` fragments are not rewritten — they resolve against the connection's default schema regardless of `withSchema`.
+
+Non-goals: no config/connection-level schema field (the connection stays schema-agnostic); no schema-defaulting of `ctx.noorm.db.describe*`'s `schema?` arg; no per-dialect gating — the qualifier means whatever the dialect makes of it (a schema on postgres/mssql, a database on mysql, an ATTACHed database on sqlite).
+
+
 ## Requires
 
 Node >= 22.13. Supports **PostgreSQL**, **MySQL**, **SQLite**, and **SQL Server**.

package/dist/index.d.ts

@@ -3820,6 +3820,31 @@ export declare class Context<DB = unknown, Procs = object, Funcs = object, Tvfs
 	get dialect(): Dialect;
 	get connected(): boolean;
 	get kysely(): Kysely<DB>;
+	/**
+	 * Derive a schema-scoped Context sharing this context's connection,
+	 * pool, and #heldConnections — same lifecycle, fresh generics for the
+	 * schema's own table/routine shape.
+	 *
+	 * Replaces rather than stacks: calling withSchema() again on an
+	 * already-derived context swaps the schema instead of nesting it,
+	 * because every derived context re-derives its `.kysely` from the
+	 * shared connection's bare instance, never from another derived
+	 * context's already-wrapped one.
+	 *
+	 * `sql`-tagged raw fragments are not rewritten by this — they resolve
+	 * against the connection's default schema regardless of this call.
+	 *
+	 * @throws Error synchronously if `name` fails identifier validation,
+	 * before any connection is borrowed or shared state is touched.
+	 *
+	 * @example
+	 * ```typescript
+	 * const acct = ctx.withSchema<AcctDB>('acct');
+	 * const rows = await acct.kysely.selectFrom('ledger').selectAll().execute();
+	 * await acct.proc('rebuild_ledger', { id: 1 }); // -> acct.rebuild_ledger
+	 * ```
+	 */
+	withSchema<SDB = DB, SProcs = Procs, SFuncs = Funcs, STvfs = Tvfs>(name: string): Context<SDB, SProcs, SFuncs, STvfs>;
 	/**
 	 * Noorm management operations.
 	 *

package/dist/index.js

@@ -15486,7 +15486,19 @@ function buildScope(db, revertFn, dialect) {
 }
 
 // src/sdk/context.ts
-var Context = class {
+var VALID_SCHEMA_NAME = /^[a-zA-Z0-9_-]+$/;
+function validateSchemaName(name) {
+  if (!name || !VALID_SCHEMA_NAME.test(name)) {
+    throw new Error(
+      `Invalid schema name: "${name}". Only alphanumeric characters, underscores, and hyphens are allowed.`
+    );
+  }
+}
+function qualifyName(schema, name) {
+  if (!schema || name.includes(".")) return name;
+  return `${schema}.${name}`;
+}
+var Context = class _Context {
   #state;
   #noorm = null;
   /**
@@ -15496,6 +15508,12 @@ var Context = class {
    * pool can never reclaim, and the context never closes.
    */
   #heldConnections = /* @__PURE__ */ new Set();
+  /**
+   * Schema this context is scoped to, or `null` for the root context.
+   * Set once by withSchema() and never mutated afterward — a chained
+   * withSchema() call derives a new Context rather than changing this.
+   */
+  #schema = null;
   constructor(config, settings, identity, options, projectRoot) {
     this.#state = {
       connection: null,
@@ -15517,7 +15535,49 @@ var Context = class {
     return this.#state.connection !== null;
   }
   get kysely() {
-    return requireConnection(this.#state).db;
+    const db = requireConnection(this.#state).db;
+    return this.#schema === null ? db : db.withSchema(this.#schema);
+  }
+  // ─────────────────────────────────────────────────────────
+  // Schema Scoping
+  // ─────────────────────────────────────────────────────────
+  /**
+   * Derive a schema-scoped Context sharing this context's connection,
+   * pool, and #heldConnections — same lifecycle, fresh generics for the
+   * schema's own table/routine shape.
+   *
+   * Replaces rather than stacks: calling withSchema() again on an
+   * already-derived context swaps the schema instead of nesting it,
+   * because every derived context re-derives its `.kysely` from the
+   * shared connection's bare instance, never from another derived
+   * context's already-wrapped one.
+   *
+   * `sql`-tagged raw fragments are not rewritten by this — they resolve
+   * against the connection's default schema regardless of this call.
+   *
+   * @throws Error synchronously if `name` fails identifier validation,
+   * before any connection is borrowed or shared state is touched.
+   *
+   * @example
+   * ```typescript
+   * const acct = ctx.withSchema<AcctDB>('acct');
+   * const rows = await acct.kysely.selectFrom('ledger').selectAll().execute();
+   * await acct.proc('rebuild_ledger', { id: 1 }); // -> acct.rebuild_ledger
+   * ```
+   */
+  withSchema(name) {
+    validateSchemaName(name);
+    const derived = new _Context(
+      this.#state.config,
+      this.#state.settings,
+      this.#state.identity,
+      this.#state.options,
+      this.#state.projectRoot
+    );
+    derived.#state = this.#state;
+    derived.#heldConnections = this.#heldConnections;
+    derived.#schema = name;
+    return derived;
   }
   // ─────────────────────────────────────────────────────────
   // Noorm Namespace
@@ -15622,10 +15682,11 @@ var Context = class {
    */
   async proc(name, ...args) {
     const params = args[0];
+    const qualifiedName4 = qualifyName(this.#schema, name);
     if (this.dialect === "postgres") {
-      return this.#executeProcPostgres(name, params);
+      return this.#executeProcPostgres(qualifiedName4, params);
     }
-    const query = buildProcCall(this.dialect, name, params);
+    const query = buildProcCall(this.dialect, qualifiedName4, params);
     const result = await query.execute(this.kysely);
     return result.rows ?? [];
   }
@@ -15678,7 +15739,7 @@ var Context = class {
     const hasParams = !(args.length === 1 && typeof args[0] === "string");
     const params = hasParams ? args[0] : void 0;
     const column = hasParams ? args[1] : args[0];
-    const query = buildFuncCall(this.dialect, name, column, params);
+    const query = buildFuncCall(this.dialect, qualifyName(this.#schema, name), column, params);
     const result = await query.execute(this.kysely);
     return result.rows?.[0] ?? null;
   }
@@ -15706,7 +15767,7 @@ var Context = class {
    */
   async tvf(name, ...args) {
     const params = args[0];
-    const query = buildTvfCall(this.dialect, name, params);
+    const query = buildTvfCall(this.dialect, qualifyName(this.#schema, name), params);
     const result = await query.execute(this.kysely);
     return result.rows ?? [];
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noormdev/sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Database schema & changeset manager SDK",
   "type": "module",
   "main": "./dist/index.js",