@cosmicdrift/kumiko-framework 0.339.0 → 0.340.0

package/dist/bun-db/index.d.ts

@@ -1,4 +1,4 @@
 export type { BunDbConnection, BunDbConnectionOptions, BunDbRunner, BunDbTx, PgListenClient, } from "./connection.js";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export type { InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectInnerJoin, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/index.js

@@ -1,4 +1,4 @@
 // bun-db: Bun.sql-basierte DB-API ohne drizzle.
 // Production-Pfad nach drizzle-removal.
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/query.d.ts

@@ -14,7 +14,7 @@ export declare function asRawClient(db: unknown): RawClient;
 export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = BunDbRunner | unknown;
-export type { OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
+export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
 type TableLike = EntityTableMeta | any;
 type WritableTable = EntityTableMeta & NotExecutorOnly;
 export type TableInfo = {
@@ -32,6 +32,26 @@ export declare function describeClosedConnectionFailure(raw: unknown, err: unkno
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
 export declare function selectMany<TRow = any>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
 export declare function fetchOne<TRow = any>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+export type JoinColumnPair = {
+    readonly left: string;
+    readonly right: string;
+};
+export type InnerJoinSpec = {
+    readonly left: TableLike;
+    readonly right: TableLike;
+    readonly on: readonly [JoinColumnPair, ...JoinColumnPair[]];
+    readonly leftWhere?: WhereObject;
+    readonly rightWhere?: WhereObject;
+    /** Fields to return per side; default: all columns of `left`, none of `right`. */
+    readonly leftFields?: readonly string[];
+    readonly rightFields?: readonly string[];
+    readonly limit?: number;
+};
+export type InnerJoinRow<TLeft, TRight> = {
+    readonly left: TLeft;
+    readonly right: TRight;
+};
+export declare function selectInnerJoin<TLeft = Record<string, unknown>, TRight = Record<string, unknown>>(db: AnyDb, spec: InnerJoinSpec): Promise<readonly InnerJoinRow<TLeft, TRight>[]>;
 export declare function insertMany<TRow = any>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
 export declare function insertOne<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
 export declare function updateMany<TRow = any>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
@@ -57,6 +77,10 @@ export declare function isTimestamptzType(pgType: string | undefined): boolean;
 export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
 export declare function upsertOnConflict<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
 export declare function upsertByPk<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+export type InsertOnConflictDoNothingOptions = {
+    readonly conflictKeys?: readonly string[];
+};
+export declare function insertOnConflictDoNothing<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
 export type IncrementCounterOptions = {
     readonly conflictKeys?: readonly string[];
     /** Extra SET clauses on conflict (e.g. lastUpdatedAt: sql\`NOW()\`). */

package/dist/bun-db/query.js

@@ -179,7 +179,7 @@ function assertNotTenantScoped(db, fnName) {
             "explicit cross-tenant op, or use a scoped TenantDb method.");
     }
 }
-const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
+const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like", "jsonText"];
 const _whereOperatorKeysExhaustive = true;
 void _whereOperatorKeysExhaustive;
 function isWhereOperator(v) {
@@ -483,10 +483,13 @@ function prepareValue(value, pgType) {
     }
     return { kind: "param", sql: "", bound: value };
 }
-function buildWhereClause(info, where, startIndex) {
+function buildWhereClause(info, where, startIndex, qualifier) {
     const conditions = [];
     const values = [];
     let idx = startIndex;
+    // Single place that renders a column reference, so a join qualifier reaches
+    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
+    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
     // multiSelect (and any other jsonb-array-of-scalars column) stores an
     // array — a filter value is one option, not the whole array, so eq/ne/in
     // must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
@@ -501,7 +504,7 @@ function buildWhereClause(info, where, startIndex) {
             // prepareJsonbValue never returns kind:"literal" (only prepareValue's
             // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
             if (p && p.kind === "param") {
-                parts.push(`${quoteIdent(col)} @> $${idx++}${p.sql}`);
+                parts.push(`${ref(col)} @> $${idx++}${p.sql}`);
                 values.push(p.bound);
             }
         }
@@ -514,7 +517,7 @@ function buildWhereClause(info, where, startIndex) {
         const col = info.columnOf(field);
         const pgType = info.pgTypeOf(col);
         if (value === null) {
-            conditions.push(`${quoteIdent(col)} IS NULL`);
+            conditions.push(`${ref(col)} IS NULL`);
         }
         else if (Array.isArray(value)) {
             if (value.length === 0) {
@@ -535,12 +538,37 @@ function buildWhereClause(info, where, startIndex) {
                         values.push(p.bound);
                     }
                 }
-                conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
+                conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
             }
         }
         else if (isWhereOperator(value)) {
+            if (value.jsonText !== undefined) {
+                if (Object.keys(value).length > 1) {
+                    throw new Error(`where: jsonText on column "${col}" cannot be combined with other operators`);
+                }
+                if (pgType !== "jsonb") {
+                    throw new Error(`where: jsonText requires a jsonb column, "${col}" is ${pgType}`);
+                }
+                const matches = Array.isArray(value.jsonText) ? value.jsonText : [value.jsonText];
+                for (const match of matches) {
+                    if (!Array.isArray(match.keys) ||
+                        match.keys.length === 0 ||
+                        !match.keys.every((k) => typeof k === "string") ||
+                        typeof match.eq !== "string") {
+                        throw new Error(`where: jsonText on column "${col}" needs non-empty string keys and a string eq`);
+                    }
+                    const lookups = match.keys.map((key) => {
+                        values.push(key);
+                        return `${ref(col)}->>$${idx++}::text`;
+                    });
+                    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
+                    values.push(match.eq);
+                    conditions.push(`(${lhs} = $${idx++})`);
+                }
+                continue;
+            }
             if (value.ne === null && Object.keys(value).length === 1) {
-                conditions.push(`${quoteIdent(col)} IS NOT NULL`);
+                conditions.push(`${ref(col)} IS NOT NULL`);
                 continue;
             }
             const opMap = {
@@ -564,17 +592,17 @@ function buildWhereClause(info, where, startIndex) {
                 if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
                     const p = prepareJsonbValue([opVal]);
                     if (p && p.kind === "param") {
-                        conditions.push(`(${quoteIdent(col)} IS NULL OR NOT (${quoteIdent(col)} @> $${idx++}${p.sql}))`);
+                        conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql}))`);
                         values.push(p.bound);
                         continue;
                     }
                 }
                 const p = prepareValue(opVal, pgType);
                 if (p.kind === "literal") {
-                    conditions.push(`${quoteIdent(col)} ${opSym} ${p.literal}`);
+                    conditions.push(`${ref(col)} ${opSym} ${p.literal}`);
                 }
                 else {
-                    conditions.push(`${quoteIdent(col)} ${opSym} $${idx++}${p.sql}`);
+                    conditions.push(`${ref(col)} ${opSym} $${idx++}${p.sql}`);
                     values.push(p.bound);
                 }
             }
@@ -598,7 +626,7 @@ function buildWhereClause(info, where, startIndex) {
                             values.push(p.bound);
                         }
                     }
-                    conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
+                    conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
                 }
             }
         }
@@ -608,7 +636,7 @@ function buildWhereClause(info, where, startIndex) {
         else {
             const p = prepareValue(value, pgType);
             if (p.kind === "literal") {
-                conditions.push(`${quoteIdent(col)} = ${p.literal}`);
+                conditions.push(`${ref(col)} = ${p.literal}`);
             }
             else {
                 // Blind-index OR rewrite (#818): if the column has a bidx
@@ -623,11 +651,11 @@ function buildWhereClause(info, where, startIndex) {
                     typeof value === "string" &&
                     !col.endsWith("_bidx") &&
                     info.hasColumn(bidxCol)) {
-                    conditions.push(`(${quoteIdent(col)} = $${idx++} OR ${quoteIdent(bidxCol)} = $${idx++})`);
+                    conditions.push(`(${ref(col)} = $${idx++} OR ${ref(bidxCol)} = $${idx++})`);
                     values.push(p.bound, computeBlindIndex(bidxKey, value));
                 }
                 else {
-                    conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
+                    conditions.push(`${ref(col)} = $${idx++}${p.sql}`);
                     values.push(p.bound);
                 }
             }
@@ -820,6 +848,76 @@ export async function fetchOne(db, table, where) {
     const rows = await selectMany(db, table, where, { limit: 1 });
     return rows[0];
 }
+const JOIN_LEFT_ALIAS = "l";
+const JOIN_RIGHT_ALIAS = "r";
+function requireJoinColumn(info, field, role) {
+    if (!info.hasColumn(field)) {
+        throw new Error(`selectInnerJoin: ${role} "${field}" is not a column of "${info.name}"`);
+    }
+    return info.columnOf(field);
+}
+export async function selectInnerJoin(db, spec) {
+    assertNotTenantScoped(db, "selectInnerJoin");
+    const leftInfo = extractTableInfo(spec.left);
+    const rightInfo = extractTableInfo(spec.right);
+    if (spec.limit !== undefined && (!Number.isInteger(spec.limit) || spec.limit < 0)) {
+        throw new Error(`selectInnerJoin: limit must be a non-negative integer, got ${spec.limit}`);
+    }
+    const leftColumns = (spec.leftFields ??
+        requireEntityTableMeta(spec.left, "selectInnerJoin").columns.map((c) => c.name)).map((field) => requireJoinColumn(leftInfo, field, "leftFields entry"));
+    const rightColumns = (spec.rightFields ?? []).map((field) => requireJoinColumn(rightInfo, field, "rightFields entry"));
+    // Positional aliases: a `<side>__<column>` scheme would hit Postgres' 63-byte
+    // identifier truncation for long column names.
+    const projected = [
+        ...leftColumns.map((column) => ({ side: "left", column })),
+        ...rightColumns.map((column) => ({ side: "right", column })),
+    ];
+    if (projected.length === 0) {
+        throw new Error("selectInnerJoin: no columns selected");
+    }
+    const selectList = projected
+        .map(({ side, column }, index) => `${quoteIdent(side === "left" ? JOIN_LEFT_ALIAS : JOIN_RIGHT_ALIAS)}.${quoteIdent(column)} AS "c${index}"`)
+        .join(", ");
+    const onPairs = spec.on.map((pair) => {
+        const leftColumn = requireJoinColumn(leftInfo, pair.left, "on.left");
+        const rightColumn = requireJoinColumn(rightInfo, pair.right, "on.right");
+        const leftRef = `${quoteIdent(JOIN_LEFT_ALIAS)}.${quoteIdent(leftColumn)}`;
+        const rightRef = `${quoteIdent(JOIN_RIGHT_ALIAS)}.${quoteIdent(rightColumn)}`;
+        return leftInfo.pgTypeOf(leftColumn) === rightInfo.pgTypeOf(rightColumn)
+            ? `${leftRef} = ${rightRef}`
+            : `${leftRef}::text = ${rightRef}::text`;
+    });
+    let sqlText = `SELECT ${selectList} FROM ${quoteIdent(leftInfo.name)} AS ${quoteIdent(JOIN_LEFT_ALIAS)} ` +
+        `INNER JOIN ${quoteIdent(rightInfo.name)} AS ${quoteIdent(JOIN_RIGHT_ALIAS)} ON ${onPairs.join(" AND ")}`;
+    const conditions = [];
+    const values = [];
+    if (spec.leftWhere && Object.keys(spec.leftWhere).length > 0) {
+        const w = buildWhereClause(leftInfo, spec.leftWhere, values.length + 1, JOIN_LEFT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (spec.rightWhere && Object.keys(spec.rightWhere).length > 0) {
+        const w = buildWhereClause(rightInfo, spec.rightWhere, values.length + 1, JOIN_RIGHT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (conditions.length > 0)
+        sqlText += ` WHERE ${conditions.join(" AND ")}`;
+    if (spec.limit !== undefined)
+        sqlText += ` LIMIT ${spec.limit}`;
+    const raw = (await unsafeReadRetrying(db, sqlText, values));
+    return raw.map((row) => {
+        const leftRow = {};
+        const rightRow = {};
+        projected.forEach(({ side, column }, index) => {
+            (side === "left" ? leftRow : rightRow)[column] = row[`c${index}`];
+        });
+        return {
+            left: coerceRow(leftRow, leftInfo),
+            right: coerceRow(rightRow, rightInfo),
+        };
+    });
+}
 // Bulk INSERT — same shape as insertOne but takes an array of rows and
 // produces one multi-VALUES statement. Mirrors drizzle's
 // `db.insert(t).values(rows[])`. Empty input is a no-op.
@@ -1064,15 +1162,20 @@ function assertValidAggregateLimits(spec) {
     if (spec.orderByValue !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByValue)) {
         throw new Error(`aggregateWhere: unknown orderByValue "${String(spec.orderByValue)}"`);
     }
+    if (spec.orderByKeys !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByKeys)) {
+        throw new Error(`aggregateWhere: unknown orderByKeys "${String(spec.orderByKeys)}"`);
+    }
 }
 function aggregateGroupOrderLimitSql(spec, dimensionCount) {
     let sqlText = "";
     if (dimensionCount > 0) {
         const positions = Array.from({ length: dimensionCount }, (_, index) => String(index + 1));
         sqlText += ` GROUP BY ${positions.join(", ")}`;
+        const keyDirection = spec.orderByKeys === "desc" ? "DESC" : "ASC";
+        const keyParts = positions.map((position) => `${position} ${keyDirection}`);
         const orderParts = spec.orderByValue === undefined
-            ? positions
-            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...positions];
+            ? keyParts
+            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...keyParts];
         sqlText += ` ORDER BY ${orderParts.join(", ")}`;
     }
     if (spec.limit !== undefined)
@@ -1162,6 +1265,24 @@ export async function upsertByPk(db, table, values, updateOnConflict) {
     });
 }
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function insertOnConflictDoNothing(db, table, values, options) {
+    assertNotTenantScoped(db, "insertOnConflictDoNothing");
+    const info = extractTableInfo(table);
+    const entries = insertEntries(info, values);
+    const conflictCols = resolveConflictColumns(table, info, options?.conflictKeys);
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO NOTHING RETURNING *`;
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "insertOnConflictDoNothing",
+        table: info.name,
+    }));
+    const first = rows[0];
+    if (!first)
+        return undefined;
+    return coerceRow(first, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function incrementCounter(db, table, values, increments, options = {}) {
     assertNotTenantScoped(db, "incrementCounter");
     const info = extractTableInfo(table);

package/dist/db/query-api.d.ts

@@ -1,2 +1,2 @@
-export type { SelectOptions, WhereObject, WhereOperator, WhereValue, } from "../db/query.js";
+export type { JsonTextMatch, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "../db/query.js";
 export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";

package/dist/db/query.d.ts

@@ -1 +1 @@
-export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -4,7 +4,7 @@
 // natural key + tenantId). Skips lifecycle hooks, field-access,
 // crypto-shredding, schema-versioning, audit-trail, read-access-log.
 // See "Was unsafeProjection.* überspringt" in
-// docs/plans/architecture/intern/step-vocabulary.md.
+// kumiko-platform/docs/archive/plans/architecture/intern/step-vocabulary.md.
 //
 // Use only on tables explicitly declared via r.requires.projection in
 // the owning feature. Aggregate-tables (registered via r.entity) are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.339.0",
+  "version": "0.340.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.339.0",
-    "@cosmicdrift/kumiko-types": "0.339.0",
+    "@cosmicdrift/kumiko-http": "0.340.0",
+    "@cosmicdrift/kumiko-types": "0.340.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.339.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.340.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Typed bun-db helpers for insert-ignore, inner joins, jsonb text filters and key-ordered aggregates",
+    "detail": "`insertOnConflictDoNothing(db, table, values, { conflictKeys? })` returns the inserted row, or `undefined` when the conflict target already exists. `selectInnerJoin(db, { left, right, on, leftWhere?, rightWhere?, leftFields?, rightFields?, limit? })` joins two tables on one or more column pairs (casting to text only when the column types differ) and returns `{ left, right }` rows; `rightFields` defaults to none, so secrets on the joined table are only read when named. The where operator `jsonText: { keys, eq }` compares `col->>key` on jsonb columns, with several keys combined through `COALESCE`. `aggregateWhere` accepts `orderByKeys: \"asc\" | \"desc\"` to sort groups by their key before `limit`. All identifiers come from the table metadata and all values are bound parameters. The helpers refuse tenant-scoped tables like the other raw-connection helpers; use the `TenantDb` methods there.",
+    "migration": "keine"
+  },
   {
     "version": "0.339.0",
     "type": "improvement",