tina4-nodejs 3.13.137 → 3.13.138

package/packages/orm/src/query.ts

@@ -1,5 +1,14 @@
-import type { QueryOptions } from "./types.js";
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+import type { FieldDefinition, QueryOptions } from "./types.js";
 import { DEFAULT_ROW_CAP } from "./database.js";
+import { quoteIdentifierAnsi } from "./adapters/sqlDialect.js";
 
 export interface ParsedQuery {
   where: string;
@@ -9,14 +18,103 @@ export interface ParsedQuery {
   params: unknown[];
 }
 
+/**
+ * Resolve a caller-supplied key to the model's DB column, or null when the key
+ * is not a declared field.
+ *
+ * tina4: ADR-0069 - identifiers that reach SQL come from the model, never the
+ * request. The key may be a declared field (property) name or that field's
+ * column name; either way the column returned is the model's own, so nothing
+ * but a declared column can be emitted. `columnOf` is the caller's existing
+ * property->column mapping (BaseModel.getDbColumn / AutoCrud's getDbCol), so
+ * the mapping rule lives in one place. Own keys only, so an inherited Object
+ * property can never resolve. Used by AutoCrud (filter + sort) and by
+ * BaseModel.find(object).
+ */
+export function resolveFieldColumn(
+  fields: Record<string, FieldDefinition>,
+  columnOf: (field: string) => string,
+  key: string,
+): string | null {
+  const field = resolveField(fields, columnOf, key);
+  return field === null ? null : columnOf(field);
+}
+
+/**
+ * The declared FIELD (property) name a key names - by the field name itself or
+ * by its column - or null. The write-side twin of resolveFieldColumn(): AutoCrud
+ * writes need the field, to validate the body and then map it to its column.
+ */
+export function resolveField(
+  fields: Record<string, FieldDefinition>,
+  columnOf: (field: string) => string,
+  key: string,
+): string | null {
+  if (Object.hasOwn(fields, key)) return key;
+  for (const field of Object.keys(fields)) {
+    if (columnOf(field) === key) return field;
+  }
+  return null;
+}
+
+/** A filter or sort key that does not resolve to a declared model field. */
+export class UnknownFieldError extends Error {
+  readonly kind: "filter" | "sort";
+  readonly field: string;
+
+  constructor(kind: "filter" | "sort", field: string) {
+    super(`Unknown ${kind} field '${field}'`);
+    this.name = "UnknownFieldError";
+    this.kind = kind;
+    this.field = field;
+  }
+}
+
+/** A query parameter whose SHAPE is wrong (a list or map where one value belongs). */
+export class InvalidQueryParameterError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidQueryParameterError";
+  }
+}
+
+const filterValueError = (field: string): InvalidQueryParameterError =>
+  new InvalidQueryParameterError(`Filter value for '${field}' must be a single value`);
+
+/**
+ * Build the list SQL from parsed query options.
+ *
+ * `quote` renders every table/column name the builder emits - pass the bound
+ * adapter's dialect (`(name) => quoteIdentifier(adapter, name)`); the default is
+ * the ANSI `"name"`.
+ *
+ * Every filter key and sort field is passed through `resolveColumn` (see
+ * resolveFieldColumn) and only the column it returns is emitted; a key it does
+ * not resolve throws UnknownFieldError before any SQL exists. With no
+ * resolver, no filter or sort key resolves (ADR-0069).
+ */
 export function buildQuery(
   tableName: string,
   options: QueryOptions,
   extraConditions?: string[],
-): { sql: string; countSql: string; params: unknown[]; limit: number; offset: number; page: number } {
+  quote: (name: string) => string = quoteIdentifierAnsi,
+  resolveColumn: (key: string) => string | null = () => null,
+): {
+  sql: string; countSql: string; params: unknown[]; limit: number; offset: number; page: number;
+  /** The same SELECT without LIMIT/OFFSET, for adapterFetch to page in the engine's own syntax. */
+  pageSql: string;
+  /** The filter parameters alone (params minus the trailing limit/offset). */
+  filterParams: unknown[];
+} {
   const conditions: string[] = [];
   const params: unknown[] = [];
 
+  const column = (kind: "filter" | "sort", key: string): string => {
+    const resolved = resolveColumn(key);
+    if (resolved === null) throw new UnknownFieldError(kind, key);
+    return quote(resolved);
+  };
+
   // Add extra conditions (soft delete, table filter)
   if (extraConditions) {
     conditions.push(...extraConditions);
@@ -25,19 +123,20 @@ export function buildQuery(
   // Parse filters
   if (options.filter) {
     for (const [field, value] of Object.entries(options.filter)) {
+      const col = column("filter", field);
       if (typeof value === "object" && value !== null) {
         // Operator filters: filter[age][gt]=25
         const ops = value as Record<string, unknown>;
         for (const [op, opVal] of Object.entries(ops)) {
-          const sqlOp = operatorMap[op];
-          if (sqlOp) {
-            conditions.push(`"${field}" ${sqlOp} ?`);
-            params.push(opVal);
-          }
+          // Own keys only: an inherited name ("constructor") is not an operator,
+          // and an unknown operator is an error, never silently dropped.
+          if (!Object.hasOwn(operatorMap, op)) throw filterValueError(field);
+          conditions.push(`${col} ${operatorMap[op]} ?`);
+          params.push(opVal);
         }
       } else {
         // Exact match: filter[name]=John
-        conditions.push(`"${field}" = ?`);
+        conditions.push(`${col} = ?`);
         params.push(value);
       }
     }
@@ -45,17 +144,19 @@ export function buildQuery(
 
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 
-  // Sort
+  // Sort: comma-separated parts, empty parts skipped, leading "-" = DESC.
+  // ORDER BY is built only from resolved columns and the words ASC / DESC.
   let orderClause = "";
   if (options.sort) {
-    const parts = options.sort.split(",").map((s) => {
-      const trimmed = s.trim();
-      if (trimmed.startsWith("-")) {
-        return `"${trimmed.slice(1)}" DESC`;
-      }
-      return `"${trimmed}" ASC`;
-    });
-    orderClause = `ORDER BY ${parts.join(", ")}`;
+    const parts: string[] = [];
+    for (const part of options.sort.split(",")) {
+      const trimmed = part.trim();
+      if (trimmed === "") continue;
+      const descending = trimmed.startsWith("-");
+      const col = column("sort", descending ? trimmed.slice(1) : trimmed);
+      parts.push(`${col} ${descending ? "DESC" : "ASC"}`);
+    }
+    if (parts.length > 0) orderClause = `ORDER BY ${parts.join(", ")}`;
   }
 
   // Pagination — PAGE-DEC-01: clamp page >= 1 BEFORE deriving offset, so
@@ -71,8 +172,9 @@ export function buildQuery(
   const page = Math.max(options.page ?? 1, 1);
   const offset = (page - 1) * limit;
 
-  const sql = `SELECT * FROM "${tableName}" ${whereClause} ${orderClause} LIMIT ? OFFSET ?`;
-  const countSql = `SELECT COUNT(*) as total FROM "${tableName}" ${whereClause}`;
+  const pageSql = `SELECT * FROM ${quote(tableName)} ${whereClause} ${orderClause}`.trimEnd();
+  const sql = `SELECT * FROM ${quote(tableName)} ${whereClause} ${orderClause} LIMIT ? OFFSET ?`;
+  const countSql = `SELECT COUNT(*) as total FROM ${quote(tableName)} ${whereClause}`;
 
   return {
     sql,
@@ -81,28 +183,42 @@ export function buildQuery(
     limit,
     offset,
     page,
+    pageSql,
+    filterParams: params,
   };
 }
 
 export function parseQueryString(query: Record<string, string>): QueryOptions {
   const options: QueryOptions = {};
 
-  // Parse filter params: filter[name]=John or filter[age][gt]=25
-  const filter: Record<string, unknown> = {};
+  // Parse filter params: filter[name]=John or filter[age][gt]=25. ANY key
+  // inside the brackets is captured - buildQuery rejects one that is not a
+  // declared field rather than it being silently ignored here (ADR-0069).
+  // A second bracket must be a known operator; a list (filter[name][]), a map
+  // (filter[name][x]) or a nested key is a wrong-shaped value and throws
+  // InvalidQueryParameterError. `sort[...]` is a list/map where a single
+  // comma-separated string belongs, and throws the same way.
+  // A null-prototype map, so a "__proto__" key is stored (and then rejected)
+  // instead of silently re-pointing the object's prototype.
+  const filter: Record<string, unknown> = Object.create(null);
   for (const [key, value] of Object.entries(query)) {
-    const filterMatch = key.match(/^filter\[(\w+)\](?:\[(\w+)\])?$/);
-    if (filterMatch) {
-      const field = filterMatch[1];
-      const operator = filterMatch[2];
-      if (operator) {
-        if (!filter[field] || typeof filter[field] !== "object") {
-          filter[field] = {};
-        }
-        (filter[field] as Record<string, string>)[operator] = value;
-      } else {
-        filter[field] = value;
-      }
+    if (key.startsWith("sort[")) {
+      throw new InvalidQueryParameterError("Query parameter 'sort' must be a single comma-separated string");
+    }
+    if (!key.startsWith("filter[")) continue;
+    const filterMatch = key.match(/^filter\[([^\]]*)\](.*)$/s);
+    if (!filterMatch) throw new UnknownFieldError("filter", key.slice("filter[".length));
+    const [, field, rest] = filterMatch;
+    if (rest === "") {
+      filter[field] = value;
+      continue;
+    }
+    const operator = rest.match(/^\[([^[\]]*)\]$/)?.[1];
+    if (operator === undefined || !Object.hasOwn(operatorMap, operator)) throw filterValueError(field);
+    if (!filter[field] || typeof filter[field] !== "object") {
+      filter[field] = {};
     }
+    (filter[field] as Record<string, string>)[operator] = value;
   }
   if (Object.keys(filter).length > 0) {
     options.filter = filter;

package/packages/orm/src/queryBuilder.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * QueryBuilder — Fluent SQL query builder for Tina4 Node.js.
  *

package/packages/orm/src/realtime/index.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 export { realtime, iceServers, type RealtimeOptions } from "./realtime.js";
 export {
   LocalStorage,

package/packages/orm/src/realtime/models/attachment.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { BaseModel } from "../../baseModel.js";
 
 /**

package/packages/orm/src/realtime/models/channel.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { BaseModel } from "../../baseModel.js";
 
 /**

package/packages/orm/src/realtime/models/channelMember.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { BaseModel } from "../../baseModel.js";
 
 /**

package/packages/orm/src/realtime/models/message.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { BaseModel } from "../../baseModel.js";
 
 /**

package/packages/orm/src/realtime/models/workspace.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { BaseModel } from "../../baseModel.js";
 
 /**

package/packages/orm/src/realtime/realtime.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { createHmac } from "node:crypto";
 import {
   Router,

package/packages/orm/src/realtime/storage.ts

@@ -1,14 +1,41 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import { createRequire } from "node:module";
 import { Log } from "../../../core/src/index.js";
+import { optionalPackageMissing } from "../../../core/src/optionalPackage.js";
 
 // ESM has no global `require`; create one so the OPTIONAL aws-sdk can be loaded
-// synchronously in S3Storage's constructor. A missing driver throws here and
-// selectStorage() catches it, degrading to local storage.
+// synchronously in S3Storage's constructor.
 const require = createRequire(import.meta.url);
 
+/** S3 needs both SDK packages, so a missing one names the command for both. */
+const S3_PACKAGES = ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"];
+
+/**
+ * Load an @aws-sdk package (an optional peer, ADR-0067). A missing one throws
+ * the actionable install error; selectStorage() catches it and logs it while
+ * degrading to local storage. Any OTHER load failure is re-thrown untouched,
+ * so an installed-but-broken SDK is never mislabelled "not installed".
+ */
+function loadAwsSdk(packageName: string): any {
+  try {
+    return require(packageName);
+  } catch (error: any) {
+    const missing = error?.code === "MODULE_NOT_FOUND" && String(error?.message ?? "").includes(`'${packageName}'`);
+    if (!missing) throw error;
+    throw optionalPackageMissing("S3Storage", S3_PACKAGES);
+  }
+}
+
 /**
  * Pluggable file storage for the realtime "files" feature. StorageBackend is
  * the interface; LocalStorage (default, zero-dependency, filesystem) and
@@ -97,7 +124,8 @@ export class LocalStorage implements StorageBackend {
 }
 
 /**
- * S3-compatible store (AWS S3, MinIO, ...). Opt-in; needs @aws-sdk/client-s3.
+ * S3-compatible store (AWS S3, MinIO, ...). Opt-in; the app installs the SDK:
+ * `npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`.
  * Presigned GET URLs let clients fetch large blobs straight from object
  * storage instead of streaming through the app.
  */
@@ -108,9 +136,12 @@ export class S3Storage implements StorageBackend {
   constructor(opts: { endpoint?: string; key?: string; secret?: string; bucket?: string; region?: string } = {}) {
     this.bucket = opts.bucket || process.env.TINA4_STORAGE_BUCKET || "";
     if (!this.bucket) throw new Error("S3Storage requires TINA4_STORAGE_BUCKET");
-    // Loaded lazily; a missing driver throws here and selectStorage falls back.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { S3Client } = require("@aws-sdk/client-s3");
+    // Loaded lazily; a missing SDK throws the install command here, and
+    // selectStorage() logs it and falls back to local storage.
+    const { S3Client } = loadAwsSdk("@aws-sdk/client-s3");
+    // url() needs the presigner; check it now so a half-installed SDK refuses
+    // at construction instead of failing on the first download link.
+    loadAwsSdk("@aws-sdk/s3-request-presigner");
     const endpoint = opts.endpoint || process.env.TINA4_STORAGE_URL;
     this.client = new S3Client({
       endpoint: endpoint || undefined,
@@ -124,13 +155,13 @@ export class S3Storage implements StorageBackend {
   }
 
   async put(key: string, data: Buffer | string, mime = "application/octet-stream"): Promise<void> {
-    const { PutObjectCommand } = require("@aws-sdk/client-s3");
+    const { PutObjectCommand } = loadAwsSdk("@aws-sdk/client-s3");
     await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: data, ContentType: mime }));
   }
 
   async get(key: string): Promise<Buffer | null> {
     try {
-      const { GetObjectCommand } = require("@aws-sdk/client-s3");
+      const { GetObjectCommand } = loadAwsSdk("@aws-sdk/client-s3");
       const res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
       const chunks: Buffer[] = [];
       for await (const chunk of res.Body as AsyncIterable<Buffer>) chunks.push(Buffer.from(chunk));
@@ -141,14 +172,14 @@ export class S3Storage implements StorageBackend {
   }
 
   async url(key: string, ttl = 3600): Promise<string | null> {
-    const { GetObjectCommand } = require("@aws-sdk/client-s3");
-    const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");
+    const { GetObjectCommand } = loadAwsSdk("@aws-sdk/client-s3");
+    const { getSignedUrl } = loadAwsSdk("@aws-sdk/s3-request-presigner");
     return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn: ttl });
   }
 
   async delete(key: string): Promise<void> {
     try {
-      const { DeleteObjectCommand } = require("@aws-sdk/client-s3");
+      const { DeleteObjectCommand } = loadAwsSdk("@aws-sdk/client-s3");
       await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
     } catch (e) {
       Log.error(`S3Storage delete failed for ${key}: ${(e as Error).message}`);
@@ -157,7 +188,7 @@ export class S3Storage implements StorageBackend {
 
   async exists(key: string): Promise<boolean> {
     try {
-      const { HeadObjectCommand } = require("@aws-sdk/client-s3");
+      const { HeadObjectCommand } = loadAwsSdk("@aws-sdk/client-s3");
       await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
       return true;
     } catch {

package/packages/orm/src/seeder.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 // Tina4 Seeder — seed database tables and ORM models with fake data.
 // Zero external dependencies.
 //

package/packages/orm/src/seederTable.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { FakeData } from "./fakeData.js";
 import { adapterExecute, adapterColumns, adapterInsert } from "./database.js";
 import { Log } from "../../core/src/index.js";

package/packages/orm/src/seederTypes.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /** Result of a seed run. */
 export interface SeedSummary {
   seeded: number;