@noormdev/sdk 1.0.0-alpha.23 → 1.0.0-alpha.25

package/dist/index.d.ts

@@ -1971,6 +1971,38 @@ export interface ImportOptions {
 	/** Truncate target table before import. Default: false. */
 	truncate?: boolean;
 }
+/**
+ * Extract the args type from a proc/func/tvf entry.
+ *
+ * Supports tuple form `[Args, Return]` and plain `void`.
+ * Non-tuple entries pass through as-is for backward compat.
+ *
+ * @example
+ * ```typescript
+ * ExtractArgs<[{ id: number }, User]>  // { id: number }
+ * ExtractArgs<void>                    // void
+ * ```
+ */
+export type ExtractArgs<E> = E extends [
+	infer A,
+	unknown
+] ? A : E;
+/**
+ * Extract the return type from a proc/func/tvf entry.
+ *
+ * Returns the second element of a `[Args, Return]` tuple.
+ * Falls back to `unknown` for `void` or non-tuple entries.
+ *
+ * @example
+ * ```typescript
+ * ExtractReturn<[{ id: number }, User]>  // User
+ * ExtractReturn<void>                    // unknown
+ * ```
+ */
+export type ExtractReturn<E> = E extends [
+	unknown,
+	infer R
+] ? R : unknown;
 export interface ContextState {
 	connection: ConnectionResult | null;
 	config: Config;
@@ -3696,18 +3728,22 @@ export declare class NoormOps {
  * the impersonated principal. Mirrors Context's query surface without
  * lifecycle or noorm ops.
  */
-export interface ImpersonatedScope<DB = unknown, Procs = object, Funcs = object> {
+export interface ImpersonatedScope<DB = unknown, Procs = object, Funcs = object, Tvfs = object> {
 	kysely: Kysely<DB>;
-	proc: <T = unknown, N extends keyof Procs & string = keyof Procs & string>(name: N, ...args: Procs[N] extends void ? [
+	proc: <N extends keyof Procs & string = keyof Procs & string, T = ExtractReturn<Procs[N]>>(name: N, ...args: ExtractArgs<Procs[N]> extends void ? [
 	] : [
-		params: Procs[N]
+		params: ExtractArgs<Procs[N]>
 	]) => Promise<T[]>;
-	func: <T = unknown, N extends keyof Funcs & string = keyof Funcs & string>(name: N, ...args: Funcs[N] extends void ? [
+	func: <N extends keyof Funcs & string = keyof Funcs & string, T = ExtractReturn<Funcs[N]>>(name: N, ...args: ExtractArgs<Funcs[N]> extends void ? [
 		column: string
 	] : [
-		params: Funcs[N],
+		params: ExtractArgs<Funcs[N]>,
 		column: string
 	]) => Promise<T>;
+	tvf: <N extends keyof Tvfs & string = keyof Tvfs & string, T = ExtractReturn<Tvfs[N]>>(name: N, ...args: ExtractArgs<Tvfs[N]> extends void ? [
+	] : [
+		params: ExtractArgs<Tvfs[N]>
+	]) => Promise<T[]>;
 	transaction: <T>(fn: (trx: Transaction<DB>) => Promise<T>) => Promise<T>;
 	revert: () => Promise<void>;
 }
@@ -3743,7 +3779,7 @@ export declare class ImpersonationError extends Error {
  * await ctx.disconnect()
  * ```
  */
-export declare class Context<DB = unknown, Procs = object, Funcs = object> {
+export declare class Context<DB = unknown, Procs = object, Funcs = object, Tvfs = object> {
 	#private;
 	constructor(config: Config, settings: Settings, identity: Identity, options: CreateContextOptions, projectRoot: string);
 	get dialect(): Dialect;
@@ -3797,8 +3833,11 @@ export declare class Context<DB = unknown, Procs = object, Funcs = object> {
 	 *
 	 * @example
 	 * ```typescript
-	 * // Named params
-	 * const users = await ctx.proc<User>('get_users', { department_id: 1 });
+	 * // Return type inferred from tuple definition
+	 * const users = await ctx.proc('get_users', { department_id: 1 });
+	 *
+	 * // Explicit return type override
+	 * const users = await ctx.proc<'get_users', SpecialUser>('get_users', { department_id: 1 });
 	 *
 	 * // Positional params
 	 * await ctx.proc('simple_proc', [42, 'hello']);
@@ -3807,9 +3846,9 @@ export declare class Context<DB = unknown, Procs = object, Funcs = object> {
 	 * await ctx.proc('refresh_cache');
 	 * ```
 	 */
-	proc<T = unknown, N extends keyof Procs & string = keyof Procs & string>(name: N, ...args: Procs[N] extends void ? [
+	proc<N extends keyof Procs & string = keyof Procs & string, T = ExtractReturn<Procs[N]>>(name: N, ...args: ExtractArgs<Procs[N]> extends void ? [
 	] : [
-		params: Procs[N]
+		params: ExtractArgs<Procs[N]>
 	]): Promise<T[]>;
 	/**
 	 * Call a database function and return the scalar result.
@@ -3819,22 +3858,45 @@ export declare class Context<DB = unknown, Procs = object, Funcs = object> {
 	 *
 	 * @example
 	 * ```typescript
-	 * // Named params + column alias
-	 * const result = await ctx.func<{ total: number }>('calc_total', { order_id: 42 }, 'total');
+	 * // Return type inferred from tuple definition
+	 * const result = await ctx.func('calc_total', { order_id: 42 }, 'total');
 	 *
-	 * // Positional params + column alias
-	 * const sum = await ctx.func<{ result: number }>('add_numbers', [1, 2], 'result');
+	 * // Explicit return type override
+	 * const result = await ctx.func<'calc_total', { total: number }>('calc_total', { order_id: 42 }, 'total');
 	 *
 	 * // No params — just column alias
-	 * const ver = await ctx.func<{ v: string }>('get_version', 'v');
+	 * const ver = await ctx.func('get_version', 'v');
 	 * ```
 	 */
-	func<T = unknown, N extends keyof Funcs & string = keyof Funcs & string>(name: N, ...args: Funcs[N] extends void ? [
+	func<N extends keyof Funcs & string = keyof Funcs & string, T = ExtractReturn<Funcs[N]>>(name: N, ...args: ExtractArgs<Funcs[N]> extends void ? [
 		column: string
 	] : [
-		params: Funcs[N],
+		params: ExtractArgs<Funcs[N]>,
 		column: string
 	]): Promise<T>;
+	/**
+	 * Call a table-valued function and return the result set.
+	 *
+	 * Generates SELECT * FROM name(...) with dialect-specific parameter
+	 * syntax. Returns multiple rows, unlike func() which returns a scalar.
+	 * Only supported on MSSQL and PostgreSQL — MySQL and SQLite throw.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Return type inferred from tuple definition
+	 * const sessions = await ctx.tvf('validate_session', { session_key: key });
+	 *
+	 * // Explicit return type override
+	 * const sessions = await ctx.tvf<'validate_session', SpecialSession>('validate_session', { session_key: key });
+	 *
+	 * // No params
+	 * const items = await ctx.tvf('get_active_items');
+	 * ```
+	 */
+	tvf<N extends keyof Tvfs & string = keyof Tvfs & string, T = ExtractReturn<Tvfs[N]>>(name: N, ...args: ExtractArgs<Tvfs[N]> extends void ? [
+	] : [
+		params: ExtractArgs<Tvfs[N]>
+	]): Promise<T[]>;
 	/**
 	 * Execute queries as a specific database principal.
 	 *
@@ -3855,8 +3917,8 @@ export declare class Context<DB = unknown, Procs = object, Funcs = object> {
 	 * await scope.revert();
 	 * ```
 	 */
-	impersonate<T>(username: string, fn: (scope: ImpersonatedScope<DB, Procs, Funcs>) => Promise<T>): Promise<T>;
-	impersonate(username: string): Promise<ImpersonatedScope<DB, Procs, Funcs>>;
+	impersonate<T>(username: string, fn: (scope: ImpersonatedScope<DB, Procs, Funcs, Tvfs>) => Promise<T>): Promise<T>;
+	impersonate(username: string): Promise<ImpersonatedScope<DB, Procs, Funcs, Tvfs>>;
 }
 /**
  * Error thrown when requireTest is enabled but config.isTest is false.
@@ -3925,7 +3987,7 @@ export declare class ProtectedConfigError extends Error {
  * const ctx = await createContext()
  * ```
  */
-export declare function createContext<DB = unknown, Procs = object, Funcs = object>(options?: CreateContextOptions): Promise<Context<DB, Procs, Funcs>>;
+export declare function createContext<DB = unknown, Procs = object, Funcs = object, Tvfs = object>(options?: CreateContextOptions): Promise<Context<DB, Procs, Funcs, Tvfs>>;
 
 export {
 	Lock$1 as Lock,

package/dist/index.js

@@ -16828,6 +16828,27 @@ function buildFuncCall(dialect, name, column, params) {
   const joined = sql.join(values.map((v) => sql`${v}`));
   return sql`SELECT ${rawName}(${joined}) AS ${rawCol}`;
 }
+function buildTvfCall(dialect, name, params) {
+  if (dialect === "sqlite") {
+    throw new Error("SQLite does not support table-valued functions.");
+  }
+  if (dialect === "mysql") {
+    throw new Error("MySQL does not support table-valued functions.");
+  }
+  const rawName = sql.raw(name);
+  if (!params || Array.isArray(params) && params.length === 0 || !Array.isArray(params) && Object.keys(params).length === 0) {
+    return sql`SELECT * FROM ${rawName}()`;
+  }
+  if (dialect === "postgres" && !Array.isArray(params)) {
+    const parts = Object.entries(params).map(
+      ([key, val]) => sql`${sql.raw(key)} => ${val}`
+    );
+    return sql`SELECT * FROM ${rawName}(${sql.join(parts)})`;
+  }
+  const values = Array.isArray(params) ? params : Object.values(params);
+  const joined = sql.join(values.map((v) => sql`${v}`));
+  return sql`SELECT * FROM ${rawName}(${joined})`;
+}
 function buildMssqlProc(rawName, params) {
   if (Array.isArray(params)) {
     const joined = sql.join(params.map((v) => sql`${v}`));
@@ -27218,6 +27239,12 @@ function buildScope(db, revertFn, dialect) {
       const result = await query.execute(db);
       return result.rows?.[0] ?? null;
     },
+    async tvf(name, ...args) {
+      const params = args[0];
+      const query = buildTvfCall(dialect, name, params);
+      const result = await query.execute(db);
+      return result.rows ?? [];
+    },
     async transaction(fn) {
       return db.transaction().execute(fn);
     },
@@ -27337,8 +27364,11 @@ var Context = class {
    *
    * @example
    * ```typescript
-   * // Named params
-   * const users = await ctx.proc<User>('get_users', { department_id: 1 });
+   * // Return type inferred from tuple definition
+   * const users = await ctx.proc('get_users', { department_id: 1 });
+   *
+   * // Explicit return type override
+   * const users = await ctx.proc<'get_users', SpecialUser>('get_users', { department_id: 1 });
    *
    * // Positional params
    * await ctx.proc('simple_proc', [42, 'hello']);
@@ -27364,14 +27394,14 @@ var Context = class {
    *
    * @example
    * ```typescript
-   * // Named params + column alias
-   * const result = await ctx.func<{ total: number }>('calc_total', { order_id: 42 }, 'total');
+   * // Return type inferred from tuple definition
+   * const result = await ctx.func('calc_total', { order_id: 42 }, 'total');
    *
-   * // Positional params + column alias
-   * const sum = await ctx.func<{ result: number }>('add_numbers', [1, 2], 'result');
+   * // Explicit return type override
+   * const result = await ctx.func<'calc_total', { total: number }>('calc_total', { order_id: 42 }, 'total');
    *
    * // No params — just column alias
-   * const ver = await ctx.func<{ v: string }>('get_version', 'v');
+   * const ver = await ctx.func('get_version', 'v');
    * ```
    */
   async func(name, ...args) {
@@ -27385,6 +27415,40 @@ var Context = class {
     const result = await query.execute(this.kysely);
     return result.rows?.[0] ?? null;
   }
+  // ─────────────────────────────────────────────────────────
+  // Table-Valued Functions
+  // ─────────────────────────────────────────────────────────
+  /**
+   * Call a table-valued function and return the result set.
+   *
+   * Generates SELECT * FROM name(...) with dialect-specific parameter
+   * syntax. Returns multiple rows, unlike func() which returns a scalar.
+   * Only supported on MSSQL and PostgreSQL — MySQL and SQLite throw.
+   *
+   * @example
+   * ```typescript
+   * // Return type inferred from tuple definition
+   * const sessions = await ctx.tvf('validate_session', { session_key: key });
+   *
+   * // Explicit return type override
+   * const sessions = await ctx.tvf<'validate_session', SpecialSession>('validate_session', { session_key: key });
+   *
+   * // No params
+   * const items = await ctx.tvf('get_active_items');
+   * ```
+   */
+  async tvf(name, ...args) {
+    if (this.dialect === "sqlite") {
+      throw new Error("SQLite does not support table-valued functions.");
+    }
+    if (this.dialect === "mysql") {
+      throw new Error("MySQL does not support table-valued functions.");
+    }
+    const params = args[0];
+    const query = buildTvfCall(this.dialect, name, params);
+    const result = await query.execute(this.kysely);
+    return result.rows ?? [];
+  }
   async impersonate(username, fn) {
     const strategy = dialectStrategy[this.dialect];
     if (!strategy) {