turbine-orm 0.81.0 → 0.90.0

package/dist/query-events.d.ts

@@ -22,7 +22,9 @@
  * package ships ESM and CJS, and a mixed graph loading both copies must still
  * see the tag a caller set through either copy.
  *
- * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * The tag reaches SQL only when the client asks for it: `sqlComment: { tag:
+ * true }` (query/sql-comment.ts) appends it to each statement as a comment,
+ * URL-encoded. Otherwise it is metadata on the in-process event only, and what
  * a listener does with it (log it, forward it to a collector) is the
  * listener's business.
  */
@@ -83,7 +85,7 @@ export declare function deferredIdentity(tag: string): {
 export declare function runReportedStatement<R extends {
     rowCount?: number | null;
     rows?: unknown[];
-}>(sink: QueryEventSink, identity: Pick<QueryEvent, 'model' | 'action' | 'batch'>, sql: string, params: unknown[], run: () => Promise<R>, wrap: (err: unknown) => unknown): Promise<R>;
+}>(sink: QueryEventSink, identity: Pick<QueryEvent, 'model' | 'action' | 'batch' | 'comment'>, sql: string, params: unknown[], run: () => Promise<R>, wrap: (err: unknown) => unknown): Promise<R>;
 /** The identity of a raw statement run through `action`. */
 export declare const rawIdentity: (action: string) => Pick<QueryEvent, "model" | "action">;
 export {};

package/dist/query-events.js

@@ -22,7 +22,9 @@
  * package ships ESM and CJS, and a mixed graph loading both copies must still
  * see the tag a caller set through either copy.
  *
- * The tag never reaches SQL. It is metadata on the in-process event only; what
+ * The tag reaches SQL only when the client asks for it: `sqlComment: { tag:
+ * true }` (query/sql-comment.ts) appends it to each statement as a comment,
+ * URL-encoded. Otherwise it is metadata on the in-process event only, and what
  * a listener does with it (log it, forward it to a collector) is the
  * listener's business.
  */

package/dist/realtime.d.ts

@@ -38,6 +38,7 @@
  *   caller's cue to resynchronise from the source of truth.
  */
 import type { PgCompatPool } from './client.js';
+import { type TurbineLogger } from './logger.js';
 /**
  * Validate a LISTEN/NOTIFY channel name. Throws ValidationError on anything
  * that isn't a plain, reasonable-length SQL identifier. This is enforced for
@@ -65,8 +66,10 @@ export interface ListenOptions {
     reconnect?: boolean | ListenReconnectOptions;
     /**
      * Called when the connection is lost and after each failed reconnect
-     * attempt. Defaults to one `console.error` line per event. The subscription
-     * keeps retrying unless `reconnect` is `false`; call `unsubscribe()` to stop.
+     * attempt. Defaults to one line per event through the client's `logger`: a
+     * `warn` (code `'listen-reconnecting'`) while the subscription retries, an
+     * `error` (code `'listen-lost'`) when it does not. The subscription keeps
+     * retrying unless `reconnect` is `false`; call `unsubscribe()` to stop.
      */
     onError?: (err: Error) => void;
     /**
@@ -110,5 +113,6 @@ export interface ActiveSubscription extends Subscription {
  * @param onClosed    invoked when the subscription ends, so the client can
  *                    drop it from its active-subscription registry
  * @param options     reconnect policy and loss/reconnect callbacks
+ * @param logger      where a loss is reported when `options.onError` is unset
  */
-export declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void, options?: ListenOptions): Promise<ActiveSubscription>;
+export declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void, options?: ListenOptions, logger?: TurbineLogger): Promise<ActiveSubscription>;

package/dist/realtime.js

@@ -39,6 +39,7 @@
  */
 import { guardCheckout } from './connection-guard.js';
 import { ConnectionError, ValidationError, wrapPgError } from './errors.js';
+import { consoleLogger, logTo } from './logger.js';
 // ---------------------------------------------------------------------------
 // Identifier validation
 // ---------------------------------------------------------------------------
@@ -125,14 +126,24 @@ async function openListenConnection(pool, channel, quotedChannel, handler, onLos
  * @param onClosed    invoked when the subscription ends, so the client can
  *                    drop it from its active-subscription registry
  * @param options     reconnect policy and loss/reconnect callbacks
+ * @param logger      where a loss is reported when `options.onError` is unset
  */
-export async function createSubscription(pool, channel, quotedChannel, handler, onClosed, options = {}) {
+export async function createSubscription(pool, channel, quotedChannel, handler, onClosed, options = {}, logger = consoleLogger) {
     const backoff = options.reconnect === false
         ? undefined
         : { ...DEFAULT_RECONNECT, ...(typeof options.reconnect === 'object' ? options.reconnect : {}) };
     const reportError = options.onError ??
         ((err) => {
-            console.error(`[turbine] $listen "${channel}": ${err.message}${backoff && !closed ? ', reconnecting' : ''}`);
+            if (backoff && !closed) {
+                logTo(logger, 'warn', `$listen "${channel}": ${err.message}, reconnecting`, {
+                    code: 'listen-reconnecting',
+                    channel,
+                    error: err,
+                });
+            }
+            else {
+                logTo(logger, 'error', `$listen "${channel}": ${err.message}`, { code: 'listen-lost', channel, error: err });
+            }
         });
     let closed = false;
     let current;

package/dist/schema-builder.d.ts

@@ -47,8 +47,12 @@ export interface ColumnDef {
     nullable?: boolean;
     /** UNIQUE constraint */
     unique?: boolean;
-    /** DEFAULT expression (raw SQL, e.g. 'now()' or "'active'") */
-    default?: string;
+    /**
+     * DEFAULT expression (raw SQL, e.g. `'now()'` or `"'active'"`). A finite number
+     * or a boolean is written as the literal it is (`5`, `true`). Anything else is
+     * refused (E003).
+     */
+    default?: string | number | boolean;
     /**
      * REFERENCES target. Either the "table.column" string form or an object with
      * referential actions ({@link ReferenceDef}).
@@ -81,6 +85,15 @@ export interface ColumnDef {
      * {@link import('./schema.js').ColumnMetadata.updatedAt}.
      */
     updatedAt?: boolean;
+    /**
+     * The TypeScript type `turbine generate` emits for this column, replacing
+     * the one derived from `type`. Mainly for `json` / `jsonb`, which otherwise
+     * generate as `unknown`: `{ type: 'jsonb', tsType: '{ theme: string }' }`.
+     * Emitted verbatim (nullability is still added), so it may name any type
+     * the generated file can see. The same override as the generator's
+     * `columnTypes` option, declared next to the column.
+     */
+    tsType?: string;
 }
 /** Postgres-level column type (uppercase, as used in DDL) */
 export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR' | 'ENUM' | 'VECTOR';
@@ -109,7 +122,21 @@ export interface ColumnConfig {
     pii: boolean;
     /** Whether this column is auto-set to the current time on update. */
     updatedAt: boolean;
+    /** Generated TypeScript type override ({@link ColumnDef.tsType}), or null / absent. */
+    tsType?: string | null;
 }
+/**
+ * Why `text` cannot be written into a generated file as a TypeScript type, or
+ * null when it can. The text lands verbatim as a member type or an alias body,
+ * so what has to hold is that it stays ONE type: brackets balance, nothing at
+ * the top level ends the member (`;` or `,`), and it holds no comment, template
+ * literal or character a type does not use. A `//` would swallow the rest of the
+ * line and a stray `}` would close the interface and start a statement.
+ *
+ * It does not check that the type is well formed or that its names exist; the
+ * compiler of the generated file does that.
+ */
+export declare function tsTypeTextProblem(text: string): string | null;
 /**
  * Explicit many-to-many relation declaration for the code-first schema.
  *
@@ -269,6 +296,28 @@ export interface DefineSchemaOptions {
 }
 /** Input format: table name -> column defs (object format) or TableDef (legacy builder) */
 type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableInput>;
+/** The table-level options of {@link TableInput}; every other key is a column. */
+type TableOptionKey = 'primaryKey' | 'manyToMany' | 'checks' | 'indexes';
+/** The expected type an unknown key is given, so the compile error names it. */
+type UnknownKey<Where extends string, K> = `unknown key "${K & string}" in ${Where}`;
+/** Every key of every member of a union (`keyof` of a union is only the shared keys). */
+type AllKeys<T> = T extends unknown ? keyof T : never;
+type KnownKeys<T, Allowed, Where extends string> = T extends readonly unknown[] ? unknown : T extends object ? {
+    [K in AllKeys<T>]?: K extends Allowed ? unknown : UnknownKey<Where, K>;
+} : unknown;
+type KnownElementKeys<A, Allowed, Where extends string> = A extends readonly (infer E)[] ? readonly KnownKeys<E, Allowed, Where>[] : unknown;
+type ColumnKeyCheck<C> = KnownKeys<C, keyof ColumnDef, 'a column'> & (C extends {
+    references: infer R;
+} ? {
+    references?: KnownKeys<R, keyof ReferenceDef, 'references'>;
+} : unknown);
+type TableKeyCheck<T> = T extends TableDef ? unknown : string extends keyof T ? unknown : {
+    [K in keyof T]: K extends 'indexes' ? KnownElementKeys<T[K], keyof ColumnIndexDef | keyof DocFieldIndexDef, 'an index'> : K extends 'checks' ? KnownElementKeys<T[K], keyof CheckDef, 'a check'> : K extends 'manyToMany' ? KnownElementKeys<T[K], keyof ManyToManyDef, 'a manyToMany relation'> : K extends TableOptionKey ? unknown : T[K] extends readonly unknown[] ? UnknownKey<'a table (not a table option, and an array is not a column)', K> : ColumnKeyCheck<T[K]>;
+};
+/** Rejects, in a literal, every key {@link defineSchema} would refuse at runtime. */
+export type SchemaKeyCheck<S> = {
+    [A in keyof S]: TableKeyCheck<S[A]>;
+};
 /**
  * Define the full database schema using plain objects.
  *
@@ -288,7 +337,7 @@ type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableIn
  * });
  * ```
  */
-export declare function defineSchema(input: SchemaInput, options?: DefineSchemaOptions): SchemaDef;
+export declare function defineSchema<S extends SchemaInput>(input: S & SchemaKeyCheck<S>, options?: DefineSchemaOptions): SchemaDef;
 export declare class ColumnBuilder {
     private _config;
     constructor();
@@ -314,7 +363,7 @@ export declare class ColumnBuilder {
     notNull(): this;
     nullable(): this;
     unique(): this;
-    default(val: string): this;
+    default(val: string | number | boolean): this;
     references(target: string, opts?: {
         onDelete?: ReferentialAction;
         onUpdate?: ReferentialAction;
@@ -323,6 +372,8 @@ export declare class ColumnBuilder {
     pii(): this;
     /** Auto-set this column to the current time on every update. Prisma's `@updatedAt`. */
     updatedAt(): this;
+    /** The TypeScript type `turbine generate` emits for this column. See {@link ColumnDef.tsType}. */
+    tsType(type: string): this;
     array(): this;
     build(): ColumnConfig;
 }