@onyx.dev/onyx-database 2.3.0 → 2.4.1

package/README.md

@@ -723,6 +723,22 @@ const maybeUser = await db
   .firstOrNull(); // or .one()
 ```
 
+### 1c) Terminal formatters
+
+```ts
+const table = await db.from('User').select('id', 'email').table();
+const tree = await db.from('User').select('id', 'email').tree({ rootLabel: 'users' });
+const csv = await db.from('User').select('id', 'email').csv({ headers: false });
+const json = await db.from('User').select('id', 'email').json();
+
+console.log(table);
+console.log(tree);
+console.log(csv);
+console.log(json);
+```
+
+`table()` renders readable box-drawing output, `tree()` expands nested objects hierarchically, `csv()` flattens nested objects with dot notation by default, and `json()` preserves the original nested structure.
+
 ### 2) Save (create/update)
 
 ```ts
@@ -1017,7 +1033,8 @@ This repository uses [Changesets](https://github.com/changesets/changesets) for
 
 1. Run `npm run changeset` to create a changeset entry.
 2. Push to `main` and the **Release** workflow opens a version PR.
-3. Tag the release to trigger `npm run release -- --dry-run` in CI.
+3. Push the version commit and create a `v*` tag to trigger the publish job.
+4. The publish job uses npm trusted publishing from GitHub Actions (OIDC), so npm must be configured with a trusted publisher for `OnyxDevTools/onyx-database` and the `Release` workflow file.
 
 ---
 

package/dist/{aggregates-BpGa31jk.d.cts → aggregates-COLPYBfv.d.cts}

@@ -1,5 +1,5 @@
 var name = "@onyx.dev/onyx-database";
-var version = "2.3.0";
+var version = "2.4.1";
 
 /**
  * Supported operators for building query criteria.
@@ -420,6 +420,98 @@ declare class QueryResults<T> extends Array<T> {
     forEachPageParallel(action: (item: T) => void | Promise<void>): Promise<void>;
 }
 
+interface TableFormatOptions {
+    /**
+     * Whether to render a header row. Defaults to `true`.
+     */
+    headers?: boolean;
+    /**
+     * Maximum width for each rendered column. Defaults to `80`.
+     */
+    maxColumnWidth?: number;
+    /**
+     * When true, nested objects expand into additional dot-notated columns.
+     * Defaults to `false`.
+     */
+    flattenNestedObjects?: boolean;
+    /**
+     * Separator used when flattening nested object keys. Defaults to `.`.
+     */
+    nestedSeparator?: string;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface TreeFormatOptions {
+    /**
+     * Label used for the root node when `includeRoot` is true. Defaults to `results`.
+     */
+    rootLabel?: string;
+    /**
+     * Field whose value should label each record node.
+     */
+    keyField?: string;
+    /**
+     * Whether to include a root node. Defaults to `true`.
+     */
+    includeRoot?: boolean;
+    /**
+     * Maximum nesting depth to expand before rendering remaining values inline.
+     * Defaults to `Infinity`.
+     */
+    maxDepth?: number;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface CsvFormatOptions {
+    /**
+     * Whether to render a header row. Defaults to `true`.
+     */
+    headers?: boolean;
+    /**
+     * Field delimiter. Defaults to `,`.
+     */
+    delimiter?: string;
+    /**
+     * Quote character. Defaults to `"`.
+     */
+    quote?: string;
+    /**
+     * Escape character used to escape embedded quotes. Defaults to `"`.
+     */
+    escape?: string;
+    /**
+     * Line ending. Defaults to `\n`.
+     */
+    newline?: '\n' | '\r\n';
+    /**
+     * When true, nested objects expand into additional dot-notated columns.
+     * Defaults to `true`.
+     */
+    flattenNestedObjects?: boolean;
+    /**
+     * Separator used when flattening nested object keys. Defaults to `.`.
+     */
+    nestedSeparator?: string;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface JsonFormatOptions {
+    /**
+     * Whether to pretty-print the JSON output. Defaults to `true`.
+     */
+    pretty?: boolean;
+    /**
+     * Indentation size used when `pretty` is true. Defaults to `2`.
+     */
+    indent?: number;
+}
+
 /**
  * Builder used to compose query conditions.
  */
@@ -618,6 +710,42 @@ interface IQueryBuilder<T = unknown> {
         records: T[];
         nextPage?: string | null;
     }>;
+    /**
+     * Executes the query and renders all matching results as a table string.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').table();
+     * console.log(output);
+     * ```
+     */
+    table(options?: TableFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as a tree string.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').tree();
+     * console.log(output);
+     * ```
+     */
+    tree(options?: TreeFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as CSV.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').csv();
+     * console.log(output);
+     * ```
+     */
+    csv(options?: CsvFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as JSON.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').json();
+     * console.log(output);
+     * ```
+     */
+    json(options?: JsonFormatOptions): Promise<string>;
     /**
      * Sets field updates for an update query.
      * @example
@@ -1805,4 +1933,4 @@ declare const replace: (attribute: string, pattern: string, repl: string) => str
 declare const format: (attribute: string, formatter: string) => string;
 declare const percentile: (attribute: string, p: number) => string;
 
-export { type SchemaEntity as $, type AiChatClient as A, type IConditionBuilder as B, type IOnyxDatabase as C, type IQueryBuilder as D, type ISaveBuilder as E, type FetchImpl as F, type OnyxConfig as G, type OnyxDocument as H, type ICascadeBuilder as I, type PublishedModelPredictionInputs as J, type PublishedModelPredictionResponse as K, type LogicalOperator as L, type PublishedModelRawPredictionRequest as M, type PublishedModelScriptPredictionRequest as N, type OnyxFacade as O, type PublishedModelPredictionInput as P, type QueryCondition as Q, type QueryCriteria as R, type QueryCriteriaOperator as S, type QueryPage as T, QueryResults as U, type QueryResultsPromise as V, type RetryOptions as W, type SchemaAttribute as X, type SchemaAttributeChange as Y, type SchemaDataType as Z, type SchemaDiff as _, type AiChatCompletionChoice as a, upper as a$, type SchemaHistoryEntry as a0, type SchemaIdentifier as a1, type SchemaIdentifierGenerator as a2, type SchemaIndex as a3, type SchemaIndexChange as a4, type SchemaIndexType as a5, type SchemaResolver as a6, type SchemaResolverChange as a7, type SchemaRevision as a8, type SchemaRevisionMetadata as a9, isNull as aA, like as aB, lower as aC, lt as aD, lte as aE, matches as aF, max as aG, median as aH, min as aI, neq as aJ, notContains as aK, notContainsIgnoreCase as aL, notIn as aM, notLike as aN, notMatches as aO, notNull as aP, notStartsWith as aQ, notWithin as aR, percentile as aS, replace as aT, name as aU, version as aV, search as aW, startsWith as aX, std as aY, substring as aZ, sum as a_, type SchemaTableDiff as aa, type SchemaTrigger as ab, type SchemaTriggerChange as ac, type SchemaTriggerEvent as ad, type SchemaUpsertRequest as ae, type SchemaValidationResult as af, type SecretMetadata as ag, type SecretRecord as ah, type SecretSaveRequest as ai, type SecretsListResponse as aj, type SelectQuery as ak, type Sort as al, type StreamAction as am, type UpdateQuery as an, asc as ao, avg as ap, between as aq, contains as ar, containsIgnoreCase as as, count as at, desc as au, eq as av, format as aw, gt as ax, gte as ay, inOp as az, type AiChatCompletionChunk as b, variance as b0, within as b1, type AiChatCompletionChunkChoice as c, type AiChatCompletionChunkDelta as d, type AiChatCompletionRequest as e, type AiChatCompletionResponse as f, type AiChatCompletionStream as g, type AiChatCompletionUsage as h, type AiChatMessage as i, type AiChatOptions as j, type AiChatRole as k, type AiClient as l, type AiErrorResponse as m, type AiModel as n, type AiModelsResponse as o, type AiRequestOptions as p, type AiScriptApprovalRequest as q, type AiScriptApprovalResponse as r, type AiTool as s, type AiToolCall as t, type AiToolCallFunction as u, type AiToolChoice as v, type AiToolFunction as w, type FetchResponse as x, type FullTextQuery as y, type ICascadeRelationshipBuilder as z };
+export { type SchemaDataType as $, type AiChatClient as A, type IConditionBuilder as B, type CsvFormatOptions as C, type IOnyxDatabase as D, type IQueryBuilder as E, type FetchImpl as F, type ISaveBuilder as G, type OnyxConfig as H, type ICascadeBuilder as I, type JsonFormatOptions as J, type OnyxDocument as K, type LogicalOperator as L, type PublishedModelPredictionInputs as M, type PublishedModelPredictionResponse as N, type OnyxFacade as O, type PublishedModelPredictionInput as P, type PublishedModelRawPredictionRequest as Q, type PublishedModelScriptPredictionRequest as R, type QueryCondition as S, type QueryCriteria as T, type QueryCriteriaOperator as U, type QueryPage as V, QueryResults as W, type QueryResultsPromise as X, type RetryOptions as Y, type SchemaAttribute as Z, type SchemaAttributeChange as _, type AiChatCompletionChoice as a, startsWith as a$, type SchemaDiff as a0, type SchemaEntity as a1, type SchemaHistoryEntry as a2, type SchemaIdentifier as a3, type SchemaIdentifierGenerator as a4, type SchemaIndex as a5, type SchemaIndexChange as a6, type SchemaIndexType as a7, type SchemaResolver as a8, type SchemaResolverChange as a9, format as aA, gt as aB, gte as aC, inOp as aD, isNull as aE, like as aF, lower as aG, lt as aH, lte as aI, matches as aJ, max as aK, median as aL, min as aM, neq as aN, notContains as aO, notContainsIgnoreCase as aP, notIn as aQ, notLike as aR, notMatches as aS, notNull as aT, notStartsWith as aU, notWithin as aV, percentile as aW, replace as aX, name as aY, version as aZ, search as a_, type SchemaRevision as aa, type SchemaRevisionMetadata as ab, type SchemaTableDiff as ac, type SchemaTrigger as ad, type SchemaTriggerChange as ae, type SchemaTriggerEvent as af, type SchemaUpsertRequest as ag, type SchemaValidationResult as ah, type SecretMetadata as ai, type SecretRecord as aj, type SecretSaveRequest as ak, type SecretsListResponse as al, type SelectQuery as am, type Sort as an, type StreamAction as ao, type TableFormatOptions as ap, type TreeFormatOptions as aq, type UpdateQuery as ar, asc as as, avg as at, between as au, contains as av, containsIgnoreCase as aw, count as ax, desc as ay, eq as az, type AiChatCompletionChunk as b, std as b0, substring as b1, sum as b2, upper as b3, variance as b4, within as b5, type AiChatCompletionChunkChoice as c, type AiChatCompletionChunkDelta as d, type AiChatCompletionRequest as e, type AiChatCompletionResponse as f, type AiChatCompletionStream as g, type AiChatCompletionUsage as h, type AiChatMessage as i, type AiChatOptions as j, type AiChatRole as k, type AiClient as l, type AiErrorResponse as m, type AiModel as n, type AiModelsResponse as o, type AiRequestOptions as p, type AiScriptApprovalRequest as q, type AiScriptApprovalResponse as r, type AiTool as s, type AiToolCall as t, type AiToolCallFunction as u, type AiToolChoice as v, type AiToolFunction as w, type FetchResponse as x, type FullTextQuery as y, type ICascadeRelationshipBuilder as z };

package/dist/{aggregates-BpGa31jk.d.ts → aggregates-COLPYBfv.d.ts}

@@ -1,5 +1,5 @@
 var name = "@onyx.dev/onyx-database";
-var version = "2.3.0";
+var version = "2.4.1";
 
 /**
  * Supported operators for building query criteria.
@@ -420,6 +420,98 @@ declare class QueryResults<T> extends Array<T> {
     forEachPageParallel(action: (item: T) => void | Promise<void>): Promise<void>;
 }
 
+interface TableFormatOptions {
+    /**
+     * Whether to render a header row. Defaults to `true`.
+     */
+    headers?: boolean;
+    /**
+     * Maximum width for each rendered column. Defaults to `80`.
+     */
+    maxColumnWidth?: number;
+    /**
+     * When true, nested objects expand into additional dot-notated columns.
+     * Defaults to `false`.
+     */
+    flattenNestedObjects?: boolean;
+    /**
+     * Separator used when flattening nested object keys. Defaults to `.`.
+     */
+    nestedSeparator?: string;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface TreeFormatOptions {
+    /**
+     * Label used for the root node when `includeRoot` is true. Defaults to `results`.
+     */
+    rootLabel?: string;
+    /**
+     * Field whose value should label each record node.
+     */
+    keyField?: string;
+    /**
+     * Whether to include a root node. Defaults to `true`.
+     */
+    includeRoot?: boolean;
+    /**
+     * Maximum nesting depth to expand before rendering remaining values inline.
+     * Defaults to `Infinity`.
+     */
+    maxDepth?: number;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface CsvFormatOptions {
+    /**
+     * Whether to render a header row. Defaults to `true`.
+     */
+    headers?: boolean;
+    /**
+     * Field delimiter. Defaults to `,`.
+     */
+    delimiter?: string;
+    /**
+     * Quote character. Defaults to `"`.
+     */
+    quote?: string;
+    /**
+     * Escape character used to escape embedded quotes. Defaults to `"`.
+     */
+    escape?: string;
+    /**
+     * Line ending. Defaults to `\n`.
+     */
+    newline?: '\n' | '\r\n';
+    /**
+     * When true, nested objects expand into additional dot-notated columns.
+     * Defaults to `true`.
+     */
+    flattenNestedObjects?: boolean;
+    /**
+     * Separator used when flattening nested object keys. Defaults to `.`.
+     */
+    nestedSeparator?: string;
+    /**
+     * Display value used for `null` and `undefined`. Defaults to an empty string.
+     */
+    nullValue?: string;
+}
+interface JsonFormatOptions {
+    /**
+     * Whether to pretty-print the JSON output. Defaults to `true`.
+     */
+    pretty?: boolean;
+    /**
+     * Indentation size used when `pretty` is true. Defaults to `2`.
+     */
+    indent?: number;
+}
+
 /**
  * Builder used to compose query conditions.
  */
@@ -618,6 +710,42 @@ interface IQueryBuilder<T = unknown> {
         records: T[];
         nextPage?: string | null;
     }>;
+    /**
+     * Executes the query and renders all matching results as a table string.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').table();
+     * console.log(output);
+     * ```
+     */
+    table(options?: TableFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as a tree string.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').tree();
+     * console.log(output);
+     * ```
+     */
+    tree(options?: TreeFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as CSV.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').csv();
+     * console.log(output);
+     * ```
+     */
+    csv(options?: CsvFormatOptions): Promise<string>;
+    /**
+     * Executes the query and renders all matching results as JSON.
+     * @example
+     * ```ts
+     * const output = await db.from('User').select('id', 'email').json();
+     * console.log(output);
+     * ```
+     */
+    json(options?: JsonFormatOptions): Promise<string>;
     /**
      * Sets field updates for an update query.
      * @example
@@ -1805,4 +1933,4 @@ declare const replace: (attribute: string, pattern: string, repl: string) => str
 declare const format: (attribute: string, formatter: string) => string;
 declare const percentile: (attribute: string, p: number) => string;
 
-export { type SchemaEntity as $, type AiChatClient as A, type IConditionBuilder as B, type IOnyxDatabase as C, type IQueryBuilder as D, type ISaveBuilder as E, type FetchImpl as F, type OnyxConfig as G, type OnyxDocument as H, type ICascadeBuilder as I, type PublishedModelPredictionInputs as J, type PublishedModelPredictionResponse as K, type LogicalOperator as L, type PublishedModelRawPredictionRequest as M, type PublishedModelScriptPredictionRequest as N, type OnyxFacade as O, type PublishedModelPredictionInput as P, type QueryCondition as Q, type QueryCriteria as R, type QueryCriteriaOperator as S, type QueryPage as T, QueryResults as U, type QueryResultsPromise as V, type RetryOptions as W, type SchemaAttribute as X, type SchemaAttributeChange as Y, type SchemaDataType as Z, type SchemaDiff as _, type AiChatCompletionChoice as a, upper as a$, type SchemaHistoryEntry as a0, type SchemaIdentifier as a1, type SchemaIdentifierGenerator as a2, type SchemaIndex as a3, type SchemaIndexChange as a4, type SchemaIndexType as a5, type SchemaResolver as a6, type SchemaResolverChange as a7, type SchemaRevision as a8, type SchemaRevisionMetadata as a9, isNull as aA, like as aB, lower as aC, lt as aD, lte as aE, matches as aF, max as aG, median as aH, min as aI, neq as aJ, notContains as aK, notContainsIgnoreCase as aL, notIn as aM, notLike as aN, notMatches as aO, notNull as aP, notStartsWith as aQ, notWithin as aR, percentile as aS, replace as aT, name as aU, version as aV, search as aW, startsWith as aX, std as aY, substring as aZ, sum as a_, type SchemaTableDiff as aa, type SchemaTrigger as ab, type SchemaTriggerChange as ac, type SchemaTriggerEvent as ad, type SchemaUpsertRequest as ae, type SchemaValidationResult as af, type SecretMetadata as ag, type SecretRecord as ah, type SecretSaveRequest as ai, type SecretsListResponse as aj, type SelectQuery as ak, type Sort as al, type StreamAction as am, type UpdateQuery as an, asc as ao, avg as ap, between as aq, contains as ar, containsIgnoreCase as as, count as at, desc as au, eq as av, format as aw, gt as ax, gte as ay, inOp as az, type AiChatCompletionChunk as b, variance as b0, within as b1, type AiChatCompletionChunkChoice as c, type AiChatCompletionChunkDelta as d, type AiChatCompletionRequest as e, type AiChatCompletionResponse as f, type AiChatCompletionStream as g, type AiChatCompletionUsage as h, type AiChatMessage as i, type AiChatOptions as j, type AiChatRole as k, type AiClient as l, type AiErrorResponse as m, type AiModel as n, type AiModelsResponse as o, type AiRequestOptions as p, type AiScriptApprovalRequest as q, type AiScriptApprovalResponse as r, type AiTool as s, type AiToolCall as t, type AiToolCallFunction as u, type AiToolChoice as v, type AiToolFunction as w, type FetchResponse as x, type FullTextQuery as y, type ICascadeRelationshipBuilder as z };
+export { type SchemaDataType as $, type AiChatClient as A, type IConditionBuilder as B, type CsvFormatOptions as C, type IOnyxDatabase as D, type IQueryBuilder as E, type FetchImpl as F, type ISaveBuilder as G, type OnyxConfig as H, type ICascadeBuilder as I, type JsonFormatOptions as J, type OnyxDocument as K, type LogicalOperator as L, type PublishedModelPredictionInputs as M, type PublishedModelPredictionResponse as N, type OnyxFacade as O, type PublishedModelPredictionInput as P, type PublishedModelRawPredictionRequest as Q, type PublishedModelScriptPredictionRequest as R, type QueryCondition as S, type QueryCriteria as T, type QueryCriteriaOperator as U, type QueryPage as V, QueryResults as W, type QueryResultsPromise as X, type RetryOptions as Y, type SchemaAttribute as Z, type SchemaAttributeChange as _, type AiChatCompletionChoice as a, startsWith as a$, type SchemaDiff as a0, type SchemaEntity as a1, type SchemaHistoryEntry as a2, type SchemaIdentifier as a3, type SchemaIdentifierGenerator as a4, type SchemaIndex as a5, type SchemaIndexChange as a6, type SchemaIndexType as a7, type SchemaResolver as a8, type SchemaResolverChange as a9, format as aA, gt as aB, gte as aC, inOp as aD, isNull as aE, like as aF, lower as aG, lt as aH, lte as aI, matches as aJ, max as aK, median as aL, min as aM, neq as aN, notContains as aO, notContainsIgnoreCase as aP, notIn as aQ, notLike as aR, notMatches as aS, notNull as aT, notStartsWith as aU, notWithin as aV, percentile as aW, replace as aX, name as aY, version as aZ, search as a_, type SchemaRevision as aa, type SchemaRevisionMetadata as ab, type SchemaTableDiff as ac, type SchemaTrigger as ad, type SchemaTriggerChange as ae, type SchemaTriggerEvent as af, type SchemaUpsertRequest as ag, type SchemaValidationResult as ah, type SecretMetadata as ai, type SecretRecord as aj, type SecretSaveRequest as ak, type SecretsListResponse as al, type SelectQuery as am, type Sort as an, type StreamAction as ao, type TableFormatOptions as ap, type TreeFormatOptions as aq, type UpdateQuery as ar, asc as as, avg as at, between as au, contains as av, containsIgnoreCase as aw, count as ax, desc as ay, eq as az, type AiChatCompletionChunk as b, std as b0, substring as b1, sum as b2, upper as b3, variance as b4, within as b5, type AiChatCompletionChunkChoice as c, type AiChatCompletionChunkDelta as d, type AiChatCompletionRequest as e, type AiChatCompletionResponse as f, type AiChatCompletionStream as g, type AiChatCompletionUsage as h, type AiChatMessage as i, type AiChatOptions as j, type AiChatRole as k, type AiClient as l, type AiErrorResponse as m, type AiModel as n, type AiModelsResponse as o, type AiRequestOptions as p, type AiScriptApprovalRequest as q, type AiScriptApprovalResponse as r, type AiTool as s, type AiToolCall as t, type AiToolCallFunction as u, type AiToolChoice as v, type AiToolFunction as w, type FetchResponse as x, type FullTextQuery as y, type ICascadeRelationshipBuilder as z };