tina4-nodejs 3.13.140 → 3.13.142

package/packages/orm/src/graph/adapters/bolt.ts

@@ -26,6 +26,12 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  * them as strings, so a Cypher `WHERE id(n) = $id` is fed `Number(id)` back.
  */
 import { GraphNode, GraphEdge, GraphResult } from "../shapes.js";
+import {
+  errorMessage,
+  nodeFromRow as toGraphNode,
+  edgeFromRow as toGraphEdge,
+  type DriverRow,
+} from "./rowMapping.js";
 import { GraphError, GraphConnectTimeout } from "../errors.js";
 import {
   resolveGraphConnectTimeout,
@@ -52,20 +58,6 @@ const driverModule: any = await import(DRIVER_PACKAGE);
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const neo4j: any = driverModule.default ?? driverModule;
 
-interface DriverRow {
-  id?: unknown;
-  labels?: unknown;
-  props?: unknown;
-  type?: unknown;
-  f?: unknown;
-  t?: unknown;
-  [key: string]: unknown;
-}
-
-function errorMessage(exc: unknown): string {
-  if (exc instanceof Error) return exc.message;
-  return String(exc);
-}
 
 /**
  * A neutral GraphNode id back to the engine's integer form. Non-numeric ids
@@ -151,12 +143,7 @@ export class BoltGraphAdapter implements GraphAdapter {
 
   // -- portable node/edge/traverse core (Cypher) -------------------------
   private nodeFromRow(row: DriverRow | undefined | null): GraphNode | null {
-    if (row === null || row === undefined) return null;
-    return new GraphNode(
-      String(row.id),
-      (row.labels as string[]) ?? [],
-      (row.props as Record<string, unknown>) ?? {},
-    );
+    return toGraphNode(row);
   }
 
   async addNode(
@@ -185,15 +172,7 @@ export class BoltGraphAdapter implements GraphAdapter {
       to_id: boltId(toId),
       props: properties ?? {},
     });
-    if (rows.length === 0) return null;
-    const row = rows[0];
-    return new GraphEdge(
-      String(row.id),
-      String(row.type),
-      String(row.f),
-      String(row.t),
-      (row.props as Record<string, unknown>) ?? {},
-    );
+    return toGraphEdge(rows[0]);
   }
 
   async getNode(nodeId: string): Promise<GraphNode | null> {

package/packages/orm/src/graph/adapters/rowMapping.ts

@@ -0,0 +1,57 @@
+/*
+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/.
+*/
+
+/**
+ * Shared driver-row mapping for the Cypher/GQL graph adapters (Bolt, Ultipa).
+ *
+ * Both drivers return a flat record with the same reserved column names —
+ * `id`, `labels`, `props`, `type`, `f`, `t` — because both adapters run the
+ * same `RETURN ... AS id, ... AS props` projection. Turning such a row into an
+ * engine-neutral GraphNode or GraphEdge is therefore identical work, so it
+ * lives here once rather than in each adapter.
+ */
+import { GraphNode, GraphEdge } from "../shapes.js";
+
+/** A flat driver record from a Cypher/GQL `RETURN ... AS <col>` projection. */
+export interface DriverRow {
+  id?: unknown;
+  labels?: unknown;
+  props?: unknown;
+  type?: unknown;
+  f?: unknown;
+  t?: unknown;
+  [key: string]: unknown;
+}
+
+/** Message of an error value, whether or not it is a real Error. */
+export function errorMessage(exc: unknown): string {
+  if (exc instanceof Error) return exc.message;
+  return String(exc);
+}
+
+/** Build an engine-neutral GraphNode from a driver row, or null when there is none. */
+export function nodeFromRow(row: DriverRow | undefined | null): GraphNode | null {
+  if (row === null || row === undefined) return null;
+  return new GraphNode(
+    String(row.id),
+    (row.labels as string[]) ?? [],
+    (row.props as Record<string, unknown>) ?? {},
+  );
+}
+
+/** Build an engine-neutral GraphEdge from a driver row, or null when there is none. */
+export function edgeFromRow(row: DriverRow | undefined | null): GraphEdge | null {
+  if (row === null || row === undefined) return null;
+  return new GraphEdge(
+    String(row.id),
+    String(row.type),
+    String(row.f),
+    String(row.t),
+    (row.props as Record<string, unknown>) ?? {},
+  );
+}

package/packages/orm/src/graph/adapters/ultipa.ts

@@ -23,6 +23,12 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  * query() is rejected by Ultipa.
  */
 import { GraphNode, GraphEdge, GraphResult } from "../shapes.js";
+import {
+  errorMessage,
+  nodeFromRow as toGraphNode,
+  edgeFromRow as toGraphEdge,
+  type DriverRow,
+} from "./rowMapping.js";
 import { GraphError, GraphConnectTimeout } from "../errors.js";
 import {
   resolveGraphConnectTimeout,
@@ -56,16 +62,6 @@ const UltipaConnectError = driver.UltipaConnectError;
  */
 const UNBOUNDED_CONNECT_SECONDS = 315_360_000; // ~10 years
 
-interface DriverRow {
-  id?: unknown;
-  labels?: unknown;
-  props?: unknown;
-  type?: unknown;
-  f?: unknown;
-  t?: unknown;
-  [key: string]: unknown;
-}
-
 /**
  * Build a GQL property map `{k1: $p_k1, ...}` plus the param dict for it.
  *
@@ -84,11 +80,6 @@ function propClause(
   return { clause: `{${pairs}}`, params };
 }
 
-function errorMessage(exc: unknown): string {
-  if (exc instanceof Error) return exc.message;
-  return String(exc);
-}
-
 export class UltipaGraphAdapter implements GraphAdapter {
   private readonly url: GraphUrl;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -154,12 +145,7 @@ export class UltipaGraphAdapter implements GraphAdapter {
 
   // -- portable node/edge/traverse core (GQL) ----------------------------
   private nodeFromRow(row: DriverRow | undefined | null): GraphNode | null {
-    if (row === null || row === undefined) return null;
-    return new GraphNode(
-      String(row.id),
-      (row.labels as string[]) ?? [],
-      (row.props as Record<string, unknown>) ?? {},
-    );
+    return toGraphNode(row);
   }
 
   async addNode(
@@ -190,15 +176,7 @@ export class UltipaGraphAdapter implements GraphAdapter {
       + `INSERT (a)-[e:\`${type}\` ${clause}]->(b) `
       + `RETURN id(e) AS id, type(e) AS type, id(a) AS f, id(b) AS t, properties(e) AS props`;
     const rows = (await this.run(gql, params, false)).dicts() as DriverRow[];
-    if (rows.length === 0) return null;
-    const row = rows[0];
-    return new GraphEdge(
-      String(row.id),
-      String(row.type),
-      String(row.f),
-      String(row.t),
-      (row.props as Record<string, unknown>) ?? {},
-    );
+    return toGraphEdge(rows[0]);
   }
 
   async getNode(nodeId: string): Promise<GraphNode | null> {

package/types/cli/src/util.d.ts

@@ -0,0 +1,28 @@
+/** Flags and positional arguments split out of a command's argv slice. */
+export interface ParsedFlags {
+    flags: Record<string, string | boolean>;
+    positional: string[];
+}
+/**
+ * Parse `--key value` and bare `--flag` arguments into flags plus positionals.
+ *
+ * A name listed in `booleanFlags` never consumes the next token; every other
+ * `--key` takes the following token as its value unless that token is itself a
+ * `--flag` (or the argv ends), in which case the key is a bare boolean.
+ */
+export declare function parseFlags(args: string[], booleanFlags?: ReadonlySet<string>): ParsedFlags;
+/**
+ * Absolute path of the first of `names` found on PATH, or null.
+ *
+ * Scans PATH directories directly (no `which` shell-out) so it behaves the same
+ * on every platform and honours a deliberately emptied PATH. Callers pass the
+ * platform-specific candidate names (e.g. `["npm.cmd", "npm.exe", "npm"]`).
+ */
+export declare function findOnPath(names: string[]): string | null;
+/**
+ * Await the ORM's async `initDatabase()` and exit(1) with a clear message on
+ * failure. The await matters: initDatabase() calls setAdapter() inside the
+ * promise, so without it the next getAdapter() throws "No database adapter
+ * configured." Shared by the migrate, rollback, and status commands.
+ */
+export declare function initDatabaseOrExit(initDatabase: () => Promise<unknown>): Promise<void>;

package/types/core/src/etag.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Does an `If-None-Match` header match the response ETag?
+ *
+ * The header may be `*`, a single tag, or a comma-separated list; the `W/`
+ * weak prefix is stripped on both sides before comparing (RFC 7232 §2.3.2
+ * weak comparison). Shared by the static file server and the compression
+ * interceptor so both answer 304 the same way.
+ */
+export declare function etagMatches(ifNoneMatch: string, etag: string): boolean;

package/types/core/src/session.d.ts

@@ -1,3 +1,4 @@
+import { RespSessionHandler } from "./sessionHandlers/respSessionHandler.js";
 export interface SessionConfig {
     /** Session backend type: "file", "redis", "valkey", "mongo", "memcached", "database" (or "db") */
     backend?: string;
@@ -95,26 +96,8 @@ export declare class FileSessionHandler implements SessionHandler {
  *
  * Or pass via SessionConfig.
  */
-export declare class RedisSessionHandler implements SessionHandler {
-    private host;
-    private port;
-    private password;
-    private prefix;
-    private db;
+export declare class RedisSessionHandler extends RespSessionHandler {
     constructor(config?: SessionConfig);
-    /**
-     * Execute a Redis command synchronously against the live server.
-     *
-     * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-     * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-     * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-     * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-     */
-    private execSync;
-    private key;
-    read(sessionId: string): SessionData | null;
-    write(sessionId: string, data: SessionData, ttl?: number): void;
-    destroy(sessionId: string): void;
 }
 export declare class Session {
     private handler;

package/types/core/src/sessionHandlers/respSessionHandler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tina4 RESP Session Handler base — the shared store logic behind Redis and
+ * Valkey, zero dependencies.
+ *
+ * Redis and Valkey speak the same RESP protocol, so the read/write/destroy
+ * transport is byte-for-byte identical between them — only the configuration
+ * variable names and the log label differ. That difference lives entirely in
+ * each subclass constructor; everything the session store actually DOES lives
+ * here, once. A subclass resolves its own host/port/password/prefix/db from
+ * config or environment, then hands a {@link RespConnection} plus a label to
+ * `super()`.
+ */
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+/** Resolved connection details a RESP session handler needs. */
+export interface RespConnection {
+    host: string;
+    port: number;
+    password: string;
+    prefix: string;
+    db: number;
+}
+/**
+ * RESP (Redis/Valkey) session handler using raw TCP — no external client.
+ *
+ * Stores session data as JSON strings with a server-side TTL for automatic
+ * expiry. A genuine key miss yields `null`; a transport/connection FAILURE
+ * (server unreachable, rejected AUTH, timeout) THROWS so the Session boundary
+ * can tell "not found" (silent) from "backend failed" (log-loud + degrade).
+ */
+export declare abstract class RespSessionHandler implements SessionHandler {
+    private readonly conn;
+    private readonly label;
+    protected constructor(conn: RespConnection, label: string);
+    /**
+     * Execute a RESP command synchronously against the live server.
+     *
+     * Delegates to the shared {@link respCommandSync} transport: a genuine key
+     * miss yields `""`, and a transport/connection FAILURE THROWS so the caller
+     * can distinguish "not found" from "backend failed". Backend-failure parity.
+     */
+    private execSync;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

package/types/core/src/sessionHandlers/valkeyHandler.d.ts

@@ -11,12 +11,7 @@
  *   TINA4_SESSION_VALKEY_PREFIX   (default: "tina4:session:")
  *   TINA4_SESSION_VALKEY_DB       (default: 0)
  */
-import type { SessionHandler } from "../session.js";
-interface SessionData {
-    _created: number;
-    _accessed: number;
-    [key: string]: unknown;
-}
+import { RespSessionHandler } from "./respSessionHandler.js";
 export interface ValkeySessionConfig {
     host?: string;
     port?: number;
@@ -41,25 +36,6 @@ export interface ValkeySessionConfig {
  * Valkey uses the same RESP protocol as Redis, so this handler is functionally
  * identical to RedisSessionHandler but with VALKEY config variable names.
  */
-export declare class ValkeySessionHandler implements SessionHandler {
-    private host;
-    private port;
-    private password;
-    private prefix;
-    private db;
+export declare class ValkeySessionHandler extends RespSessionHandler {
     constructor(config?: ValkeySessionConfig);
-    /**
-     * Execute a RESP command synchronously against the live Valkey server.
-     *
-     * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-     * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-     * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-     * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-     */
-    private execSync;
-    private key;
-    read(sessionId: string): SessionData | null;
-    write(sessionId: string, data: SessionData, ttl: number): void;
-    destroy(sessionId: string): void;
 }
-export {};

package/types/core/src/upstreamResponse.d.ts

@@ -0,0 +1,10 @@
+import type { Tina4Response } from "./types.js";
+/**
+ * Relay a drained upstream (proxied) response to the client.
+ *
+ * The body is read to a string once, then returned as JSON when it parses and
+ * as raw text with the upstream Content-Type otherwise, keeping the upstream
+ * status either way. Shared by the dev-admin supervisor proxy and the feedback
+ * agent proxy so both pass a backend response through identically.
+ */
+export declare function relayUpstreamResponse(res: Tina4Response, upstream: Response): Promise<void>;

package/types/core/src/websocket.d.ts

@@ -131,6 +131,25 @@ export declare function parseFrame(data: Buffer): {
     payload: Buffer;
     bytesConsumed: number;
 } | null;
+/**
+ * Reassembles fragmented messages (RFC 6455 section 5.4). A browser sends a large message - a pasted image in a chat,
+ * base64 inside JSON - as a TEXT or BINARY frame with FIN clear, then CONTINUATION frames; control frames may arrive
+ * between the pieces. Returns a complete message when one is done, a control frame as it comes, and null while a
+ * message is still arriving. A CONTINUATION with no message started is dropped. Mirrors the Python master
+ * (tina4_python.websocket _handle_frame). One per connection.
+ */
+export declare class MessageAssembler {
+    private parts;
+    private opcode;
+    push(frame: {
+        fin: boolean;
+        opcode: number;
+        payload: Buffer;
+    }): {
+        opcode: number;
+        payload: Buffer;
+    } | null;
+}
 export declare class WebSocketServer {
     private port;
     private server;
@@ -271,6 +290,8 @@ export declare class WebSocketServer {
      */
     private startIdleReaper;
     private handleUpgrade;
+    private readonly assemblers;
+    private assemblerFor;
     private processBuffer;
     private removeClientFromAllRooms;
 }

package/types/orm/src/graph/adapters/rowMapping.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared driver-row mapping for the Cypher/GQL graph adapters (Bolt, Ultipa).
+ *
+ * Both drivers return a flat record with the same reserved column names —
+ * `id`, `labels`, `props`, `type`, `f`, `t` — because both adapters run the
+ * same `RETURN ... AS id, ... AS props` projection. Turning such a row into an
+ * engine-neutral GraphNode or GraphEdge is therefore identical work, so it
+ * lives here once rather than in each adapter.
+ */
+import { GraphNode, GraphEdge } from "../shapes.js";
+/** A flat driver record from a Cypher/GQL `RETURN ... AS <col>` projection. */
+export interface DriverRow {
+    id?: unknown;
+    labels?: unknown;
+    props?: unknown;
+    type?: unknown;
+    f?: unknown;
+    t?: unknown;
+    [key: string]: unknown;
+}
+/** Message of an error value, whether or not it is a real Error. */
+export declare function errorMessage(exc: unknown): string;
+/** Build an engine-neutral GraphNode from a driver row, or null when there is none. */
+export declare function nodeFromRow(row: DriverRow | undefined | null): GraphNode | null;
+/** Build an engine-neutral GraphEdge from a driver row, or null when there is none. */
+export declare function edgeFromRow(row: DriverRow | undefined | null): GraphEdge | null;