@getstrata/core 2.2.25 → 2.2.26

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @getstrata/core changelog
 
+## 2.2.26
+
+- Integer validation checks complete safe values instead of accepting numeric prefixes. Whole signed decimal form strings, optional values and existing error messages remain supported; `allowNumericStrings: false` requires JSON numbers. Validated strings are not implicitly cast. Invalid range bounds reject at configuration time.
+- `SqlOutbox.getDelivery(eventId, listenerName)` provides bounded read-only status/attempt inspection under the caller's active connection and RLS scope. It returns no payloads, owner tokens or provider errors, never establishes bypass, and remains an advisory snapshot distinct from atomic replay.
+- Repository and fluent `sumBy(groupColumn, column)` return typed groups with database textual totals, preserving precision without implicit JavaScript number conversion. Bound/protected predicates, soft deletes and transaction/RLS scopes are preserved; unsupported transformations reject explicitly. Native Postgres, MySQL and SQLite regressions cover precision, null groups, rollback and overflow behavior.
+
 ## 2.2.25
 
 Queue worker run loops recover native Redis connection closure with bounded backoff and a fresh connection. Uncertain Redis mutations are not replayed; retained reservations and retries use normal recovery. Explicit closure remains terminal and non-connection errors remain fatal. Native poll/ack closure regressions cover Streams and list transports.

package/dist/core/database/baseRepository.d.ts

@@ -78,6 +78,11 @@ declare class BaseRepository<TEntity extends object, PrimaryKey extends keyof TE
     protected countWhere(where?: QueryWhere<TEntity>, options?: Pick<QueryOptions<TEntity>, "withTrashed" | "onlyTrashed" | "joins" | "groupBy">, whereNodes?: readonly WhereNode<TEntity>[]): Promise<number>;
     protected averageColumn(column: keyof TEntity & string, where?: QueryWhere<TEntity>): Promise<number>;
     protected averageExpression(expression: string, alias: string, where?: QueryWhere<TEntity>): Promise<number>;
+    /** One plain grouped projection; SQL numeric totals remain exact text, never implicit JS numbers. */
+    sumBy<K extends keyof TEntity & string>(groupColumn: K, column: keyof TEntity & string, options?: ExtendedQueryOptions<TEntity>): Promise<Array<{
+        value: TEntity[K] | null;
+        sum: string | null;
+    }>>;
     sum(column: keyof TEntity & string, where?: QueryWhere<TEntity>): Promise<number>;
     avg(column: keyof TEntity & string, where?: QueryWhere<TEntity>): Promise<number>;
     min(column: keyof TEntity & string, where?: QueryWhere<TEntity>): Promise<number>;

package/dist/core/database/query.d.ts

@@ -36,6 +36,11 @@ declare function buildProjectionQuery<TEntity extends object>(table: TableDefini
     params: unknown[];
 };
 declare function assertSafeProjectionExpression(expression: string): void;
+/** Fixed aliases and textual totals avoid driver-dependent JavaScript precision loss. */
+declare function buildGroupedSumQuery<TEntity extends object, K extends keyof TEntity & string>(table: TableDefinition<TEntity>, groupColumn: K, column: keyof TEntity & string, options?: QueryOptions<TEntity>, whereNodes?: readonly WhereNode<TEntity>[]): {
+    text: string;
+    params: unknown[];
+};
 declare function buildGroupedCountQuery<TEntity extends object, K extends keyof TEntity & string>(table: TableDefinition<TEntity>, column: K, where?: QueryWhere<TEntity>, options?: Pick<QueryOptions<TEntity>, "withTrashed" | "onlyTrashed">): {
     text: string;
     params: unknown[];
@@ -73,4 +78,4 @@ declare function buildConditionalWriteQuery<TEntity extends object, PrimaryKey e
     text: string;
     params: unknown[];
 };
-export { assertSafeProjectionExpression, buildAdvancedWhereClause, buildConditionalWriteQuery, buildCountQuery, buildDeleteByIdQuery, buildGroupedCountQuery, buildIncrementQuery, buildInsertQuery, buildJoinClause, buildOrderByClause, buildProjectionQuery, buildQueryWhereClause, buildRestoreByIdQuery, buildSelectQuery, buildSoftDeleteByIdQuery, buildUpdateQuery, buildUpsertQuery, buildWhereClause, parseQualifiedColumn, qualifyColumn, quoteIdentifier, resolveQualifiedColumn, resolveSoftDeleteColumn, };
+export { assertSafeProjectionExpression, buildAdvancedWhereClause, buildConditionalWriteQuery, buildCountQuery, buildDeleteByIdQuery, buildGroupedCountQuery, buildGroupedSumQuery, buildIncrementQuery, buildInsertQuery, buildJoinClause, buildOrderByClause, buildProjectionQuery, buildQueryWhereClause, buildRestoreByIdQuery, buildSelectQuery, buildSoftDeleteByIdQuery, buildUpdateQuery, buildUpsertQuery, buildWhereClause, parseQualifiedColumn, qualifyColumn, quoteIdentifier, resolveQualifiedColumn, resolveSoftDeleteColumn, };

package/dist/core/database/repositoryQuery.d.ts

@@ -47,6 +47,10 @@ declare class RepositoryQuery<TEntity extends object, PrimaryKey extends keyof T
     private assertNoMutationEagerLoads;
     get(): Promise<Array<TEntity & LoadedRow>>;
     first(): Promise<(TEntity & LoadedRow) | null>;
+    sumBy<K extends keyof TEntity & string>(groupColumn: K, column: keyof TEntity & string): Promise<Array<{
+        value: TEntity[K] | null;
+        sum: string | null;
+    }>>;
     count(): Promise<number>;
     pluck<K extends keyof TEntity & string>(column: K): Promise<Array<TEntity[K]>>;
     pluck<K extends keyof TEntity & string, KK extends keyof TEntity & string>(column: K, keyBy: KK): Promise<Map<TEntity[KK], TEntity[K]>>;

package/dist/core/events/outbox/index.d.ts

@@ -13,6 +13,12 @@ interface DurableListener {
         signal: AbortSignal;
     }): Promise<void>;
 }
+type OutboxDeliveryStatus = "pending" | "processing" | "failed" | "completed";
+interface OutboxDeliverySnapshot {
+    readonly status: OutboxDeliveryStatus;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+}
 interface SqlOutboxOptions {
     listeners: readonly DurableListener[];
     leaseMs?: number;
@@ -31,6 +37,8 @@ declare class SqlOutbox {
     private readonly tenantResolver;
     constructor(options: SqlOutboxOptions);
     hasListener(name: string, event?: string): boolean;
+    /** Read-only advisory observation: caller owns tenant/RLS scope; no implicit bypass. */
+    getDelivery(eventId: string, listenerName: string): Promise<OutboxDeliverySnapshot | null>;
     publish(name: string, payload: unknown, options?: {
         id?: string;
         version?: number;
@@ -53,5 +61,5 @@ declare class SqlOutbox {
 export type { OutboxMetricState, OutboxMetricsCollector, OutboxMetricsOptions, OutboxMetricsSnapshot, } from "./metrics";
 export { createOutboxMetricsCollector, renderOutboxMetrics } from "./metrics";
 export { createOutboxMigration } from "./migration";
-export type { DurableEvent, DurableListener, SqlOutboxOptions };
+export type { DurableEvent, DurableListener, OutboxDeliverySnapshot, OutboxDeliveryStatus, SqlOutboxOptions, };
 export { SqlOutbox };

package/dist/core/validation/rules.d.ts

@@ -7,11 +7,15 @@ declare function maxLength(maximum: number): ValidationRule;
 declare function pattern(expression: RegExp): ValidationRule;
 declare function enumRule<TValue extends string>(allowedValues: readonly TValue[]): ValidationRule;
 declare function optional(): ValidationRule;
-declare function integerRule(): ValidationRule;
+interface IntegerValidationOptions {
+    /** Default true preserves whole decimal form strings; false requires JSON numbers. */
+    allowNumericStrings?: boolean;
+}
+declare function integerRule(options?: IntegerValidationOptions): ValidationRule;
 declare function emailRule(): ValidationRule;
 declare function confirmed(fieldName: string): ValidationRule;
-declare function positiveIntegerRule(): ValidationRule;
-declare function integerRange(minimum: number, maximum: number): ValidationRule;
+declare function positiveIntegerRule(options?: IntegerValidationOptions): ValidationRule;
+declare function integerRange(minimum: number, maximum: number, options?: IntegerValidationOptions): ValidationRule;
 declare function validateObject(payload: unknown, schema: ValidationSchema): Record<string, unknown>;
-export type { ValidationRule, ValidationSchema };
+export type { IntegerValidationOptions, ValidationRule, ValidationSchema };
 export { confirmed, emailRule, enumRule, integerRange, integerRule, maxLength, minLength, optional, pattern, positiveIntegerRule, required, stringRule, validateObject, };

package/dist/entries/database/query.js

@@ -429,6 +429,20 @@ function assertSafeProjectionExpression(expression) {
     throw new Error(`Unsafe projection expression: ${expression}`);
   }
 }
+function buildGroupedSumQuery(table, groupColumn, column, options = {}, whereNodes = options.whereNodes ?? []) {
+  if (!table.columns.includes(groupColumn) || !table.columns.includes(column))
+    throw new TypeError("Grouped sums require declared columns.");
+  for (const key of Object.keys(options))
+    if (!["where", "whereNodes", "withTrashed", "onlyTrashed"].includes(key))
+      throw new TypeError("Grouped sums do not support joins, selection, ordering, pagination, grouping or locks.");
+  const group = qualifyColumn(table.name, groupColumn);
+  const total = currentSqlDialect().castToText(`SUM(${qualifyColumn(table.name, column)})`);
+  const { clause, params } = buildQueryWhereClause(table, options, whereNodes);
+  return {
+    text: `SELECT ${group} AS ${quoteIdentifier("value")}, ${total} AS ${quoteIdentifier("sum")} FROM ${quoteIdentifier(table.name)}${clause} GROUP BY ${group} ORDER BY ${group} ASC`,
+    params
+  };
+}
 function buildGroupedCountQuery(table, column, where = {}, options = {}) {
   const qualifiedColumn = qualifyColumn(table.name, column);
   const { clause, params } = buildQueryWhereClause(table, {
@@ -608,6 +622,7 @@ export {
   buildCountQuery,
   buildDeleteByIdQuery,
   buildGroupedCountQuery,
+  buildGroupedSumQuery,
   buildIncrementQuery,
   buildInsertQuery,
   buildJoinClause,

package/dist/entries/database/repositoryQuery.js

@@ -453,6 +453,20 @@ function assertSafeProjectionExpression(expression) {
     throw new Error(`Unsafe projection expression: ${expression}`);
   }
 }
+function buildGroupedSumQuery(table, groupColumn, column, options = {}, whereNodes = options.whereNodes ?? []) {
+  if (!table.columns.includes(groupColumn) || !table.columns.includes(column))
+    throw new TypeError("Grouped sums require declared columns.");
+  for (const key of Object.keys(options))
+    if (!["where", "whereNodes", "withTrashed", "onlyTrashed"].includes(key))
+      throw new TypeError("Grouped sums do not support joins, selection, ordering, pagination, grouping or locks.");
+  const group = qualifyColumn(table.name, groupColumn);
+  const total = currentSqlDialect().castToText(`SUM(${qualifyColumn(table.name, column)})`);
+  const { clause, params } = buildQueryWhereClause(table, options, whereNodes);
+  return {
+    text: `SELECT ${group} AS ${quoteIdentifier("value")}, ${total} AS ${quoteIdentifier("sum")} FROM ${quoteIdentifier(table.name)}${clause} GROUP BY ${group} ORDER BY ${group} ASC`,
+    params
+  };
+}
 function buildGroupedCountQuery(table, column, where = {}, options = {}) {
   const qualifiedColumn = qualifyColumn(table.name, column);
   const { clause, params } = buildQueryWhereClause(table, {
@@ -1124,6 +1138,11 @@ class RepositoryQuery {
     const attached = await this.attach(rows);
     return attached[0] ?? null;
   }
+  async sumBy(groupColumn, column) {
+    if (this.eagerLoads.length)
+      throw new TypeError("Grouped sums do not support eager loading.");
+    return this.repository.sumBy(groupColumn, column, this.buildOptions());
+  }
   async count() {
     return await this.repository.count(this.buildOptions());
   }

package/dist/entries/validation/rules.js

@@ -69,15 +69,21 @@ function optional() {
     return;
   };
 }
-function integerRule() {
+function integerValue(value, options) {
+  if (typeof value === "number")
+    return Number.isSafeInteger(value) ? value : undefined;
+  if (options.allowNumericStrings !== false && typeof value === "string" && /^[+-]?\d+$/.test(value.trim())) {
+    const parsed = Number(value.trim());
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+  }
+  return;
+}
+function integerRule(options = {}) {
   return (field, value) => {
-    if (value === undefined || value === null || value === "") {
+    if (value === undefined || value === null || value === "")
       return;
-    }
-    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
-    if (!Number.isInteger(parsed)) {
+    if (integerValue(value, options) === undefined)
       return `"${field}" must be an integer.`;
-    }
     return;
   };
 }
@@ -103,27 +109,25 @@ function confirmed(fieldName) {
     return;
   };
 }
-function positiveIntegerRule() {
+function positiveIntegerRule(options = {}) {
   return (field, value) => {
-    if (value === undefined || value === null || value === "") {
+    if (value === undefined || value === null || value === "")
       return;
-    }
-    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
-    if (!Number.isInteger(parsed) || parsed <= 0) {
+    const parsed = integerValue(value, options);
+    if (parsed === undefined || parsed <= 0)
       return `"${field}" must be a positive integer.`;
-    }
     return;
   };
 }
-function integerRange(minimum, maximum) {
+function integerRange(minimum, maximum, options = {}) {
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum > maximum)
+    throw new TypeError("Integer range bounds must be safe integers in ascending order.");
   return (field, value) => {
-    if (value === undefined || value === null || value === "") {
+    if (value === undefined || value === null || value === "")
       return;
-    }
-    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
-    if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+    const parsed = integerValue(value, options);
+    if (parsed === undefined || parsed < minimum || parsed > maximum)
       return `"${field}" must be an integer between ${minimum} and ${maximum}.`;
-    }
     return;
   };
 }

package/dist/index.js

@@ -4925,6 +4925,20 @@ function assertSafeProjectionExpression(expression) {
     throw new Error(`Unsafe projection expression: ${expression}`);
   }
 }
+function buildGroupedSumQuery(table, groupColumn, column, options = {}, whereNodes = options.whereNodes ?? []) {
+  if (!table.columns.includes(groupColumn) || !table.columns.includes(column))
+    throw new TypeError("Grouped sums require declared columns.");
+  for (const key of Object.keys(options))
+    if (!["where", "whereNodes", "withTrashed", "onlyTrashed"].includes(key))
+      throw new TypeError("Grouped sums do not support joins, selection, ordering, pagination, grouping or locks.");
+  const group = qualifyColumn(table.name, groupColumn);
+  const total = currentSqlDialect().castToText(`SUM(${qualifyColumn(table.name, column)})`);
+  const { clause, params } = buildQueryWhereClause(table, options, whereNodes);
+  return {
+    text: `SELECT ${group} AS ${quoteIdentifier("value")}, ${total} AS ${quoteIdentifier("sum")} FROM ${quoteIdentifier(table.name)}${clause} GROUP BY ${group} ORDER BY ${group} ASC`,
+    params
+  };
+}
 function buildGroupedCountQuery(table, column, where = {}, options = {}) {
   const qualifiedColumn = qualifyColumn(table.name, column);
   const { clause, params } = buildQueryWhereClause(table, {
@@ -5623,6 +5637,11 @@ class RepositoryQuery {
     const attached = await this.attach(rows);
     return attached[0] ?? null;
   }
+  async sumBy(groupColumn, column) {
+    if (this.eagerLoads.length)
+      throw new TypeError("Grouped sums do not support eager loading.");
+    return this.repository.sumBy(groupColumn, column, this.buildOptions());
+  }
   async count() {
     return await this.repository.count(this.buildOptions());
   }
@@ -6235,6 +6254,11 @@ class BaseRepository {
     const [row] = await this.connection.unsafe(text, params);
     return Number(row?.[alias] ?? 0);
   }
+  async sumBy(groupColumn, column, options = {}) {
+    const { whereNodes, ...queryOptions } = options;
+    const { text, params } = buildGroupedSumQuery(this.table, groupColumn, column, queryOptions, whereNodes ?? []);
+    return withDatabaseErrorHandling(() => this.connection.unsafe(text, params));
+  }
   async sum(column, where = {}) {
     return await this.aggregateColumn("SUM", column, where);
   }
@@ -10446,6 +10470,22 @@ class SqlOutbox {
     const listener = this.listeners.get(name);
     return listener !== undefined && (event === undefined || listener.event === event);
   }
+  async getDelivery(eventId, listenerName) {
+    identifier(eventId, 64);
+    identifier(listenerName, 128);
+    const p = placeholders(2);
+    const [row] = await repositoryConnection.unsafe(`SELECT status, attempts, max_attempts FROM strata_outbox_delivery WHERE event_id = ${p[0]} AND listener_name = ${p[1]} LIMIT 1`, [eventId, listenerName]);
+    if (!row)
+      return null;
+    const attempts = Number(row.attempts);
+    const maxAttempts = Number(row.max_attempts);
+    if (!Number.isSafeInteger(attempts) || attempts < 0 || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
+      throw new Error("Invalid outbox delivery snapshot.");
+    const status = row.status;
+    if (status !== "pending" && status !== "processing" && status !== "failed" && status !== "completed")
+      throw new Error("Invalid outbox delivery snapshot.");
+    return { status, attempts, maxAttempts };
+  }
   async publish(name, payload, options = {}) {
     if (!hasActiveTransaction())
       throw new Error("Durable publication requires an active business transaction.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.25",
+  "version": "2.2.26",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",