@ragable/sdk 0.6.12 → 0.6.13

package/dist/index.d.mts

@@ -322,6 +322,28 @@ interface Filter {
     column: string;
     value: unknown;
 }
+/**
+ * Chainable SELECT (PostgREST / Supabase-style). Filters and modifiers apply to the **base**
+ * table of the query (the table passed to `client.from(...)`); the `select` string controls columns
+ * and **resource embedding** (joins).
+ *
+ * **Joins** use the same embedded `select` syntax as
+ * [Supabase `.select()`](https://supabase.com/docs/reference/javascript/select) / PostgREST, for example:
+ * - `*,related_table(*)` — include related rows
+ * - `related_table!inner(*)` — inner-style embed
+ * - `related_table!fkey_column_or_constraint(*)` — disambiguate when multiple FKs exist
+ * - `alias:related_table(*)` — rename the JSON key for the nested object/array
+ *
+ * **Ragable limits** (server-side): only **one level** of embedding is supported — no nested
+ * `relation(nested(...))`. Prefer embed aliases above; top-level column rename forms like
+ * `alias:column` may not be accepted for scalar columns.
+ *
+ * **API note:** Supabase’s second `select(columns, options?)` argument (`count`, `head`, etc.) is
+ * not supported in Ragable yet; joins use the **first** argument only.
+ *
+ * For nested result shapes, pass a type argument on {@link PostgrestTableApi.select}:
+ * `from('orders').select<OrderWithLines>(\`*, lines (*)\`)`.
+ */
 declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>, D extends RagableDatabase = DefaultRagableDatabase, T extends RagableTableNames<D> = RagableTableNames<D>> implements PromiseLike<PostgrestResult<Row[]>> {
     private readonly pgFetch;
     private readonly databaseInstanceId;
@@ -509,7 +531,14 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     private readonly databaseInstanceId;
     private readonly table;
     constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: TableName extends string ? string : string);
-    select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>, Database, TableName>;
+    /**
+     * Start a SELECT. Pass a PostgREST `select` string; use embedded resources for joins — see
+     * {@link PostgrestSelectBuilder}.
+     *
+     * @param columns Column list and optional embeds (default `"*"`). Omitted or `"*"` means all base columns.
+     * @typeParam RowResult Row shape returned by the query; defaults to this table’s `Row`. Override when using joins.
+     */
+    select<RowResult extends Record<string, unknown> = TableRow<Database, TableName>>(columns?: string): PostgrestSelectBuilder<RowResult, Database, TableName>;
     insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], ...rest: unknown[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
     update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>, Database, TableName>;

package/dist/index.d.ts

@@ -322,6 +322,28 @@ interface Filter {
     column: string;
     value: unknown;
 }
+/**
+ * Chainable SELECT (PostgREST / Supabase-style). Filters and modifiers apply to the **base**
+ * table of the query (the table passed to `client.from(...)`); the `select` string controls columns
+ * and **resource embedding** (joins).
+ *
+ * **Joins** use the same embedded `select` syntax as
+ * [Supabase `.select()`](https://supabase.com/docs/reference/javascript/select) / PostgREST, for example:
+ * - `*,related_table(*)` — include related rows
+ * - `related_table!inner(*)` — inner-style embed
+ * - `related_table!fkey_column_or_constraint(*)` — disambiguate when multiple FKs exist
+ * - `alias:related_table(*)` — rename the JSON key for the nested object/array
+ *
+ * **Ragable limits** (server-side): only **one level** of embedding is supported — no nested
+ * `relation(nested(...))`. Prefer embed aliases above; top-level column rename forms like
+ * `alias:column` may not be accepted for scalar columns.
+ *
+ * **API note:** Supabase’s second `select(columns, options?)` argument (`count`, `head`, etc.) is
+ * not supported in Ragable yet; joins use the **first** argument only.
+ *
+ * For nested result shapes, pass a type argument on {@link PostgrestTableApi.select}:
+ * `from('orders').select<OrderWithLines>(\`*, lines (*)\`)`.
+ */
 declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>, D extends RagableDatabase = DefaultRagableDatabase, T extends RagableTableNames<D> = RagableTableNames<D>> implements PromiseLike<PostgrestResult<Row[]>> {
     private readonly pgFetch;
     private readonly databaseInstanceId;
@@ -509,7 +531,14 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     private readonly databaseInstanceId;
     private readonly table;
     constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: TableName extends string ? string : string);
-    select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>, Database, TableName>;
+    /**
+     * Start a SELECT. Pass a PostgREST `select` string; use embedded resources for joins — see
+     * {@link PostgrestSelectBuilder}.
+     *
+     * @param columns Column list and optional embeds (default `"*"`). Omitted or `"*"` means all base columns.
+     * @typeParam RowResult Row shape returned by the query; defaults to this table’s `Row`. Override when using joins.
+     */
+    select<RowResult extends Record<string, unknown> = TableRow<Database, TableName>>(columns?: string): PostgrestSelectBuilder<RowResult, Database, TableName>;
     insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], ...rest: unknown[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
     update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>, Database, TableName>;

package/dist/index.js

@@ -1531,6 +1531,13 @@ var PostgrestTableApi = class {
     this.databaseInstanceId = databaseInstanceId;
     this.table = table;
   }
+  /**
+   * Start a SELECT. Pass a PostgREST `select` string; use embedded resources for joins — see
+   * {@link PostgrestSelectBuilder}.
+   *
+   * @param columns Column list and optional embeds (default `"*"`). Omitted or `"*"` means all base columns.
+   * @typeParam RowResult Row shape returned by the query; defaults to this table’s `Row`. Override when using joins.
+   */
   select(columns = "*") {
     return new PostgrestSelectBuilder(
       this.pgFetch,