tina4-nodejs 3.13.103 → 3.13.105

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

@@ -74,7 +74,13 @@ export interface QueueBackendInterface {
     close(): void;
     complete?(queue: string, id: string): void;
     fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
-    retry?(queue: string, id: string, delaySeconds?: number): void;
+    /**
+     * Explicit manual re-queue: returns true if the id was found and revived,
+     * false otherwise (parity with Python's backend.retry_job()). A backend may
+     * legacy-return void; callers coerce a void return to true so nothing that
+     * used to be reported as success silently flips to failure.
+     */
+    retry?(queue: string, id: string, delaySeconds?: number): boolean | void;
     deadLetters?(queue: string, maxRetries?: number): QueueJob[];
     failed?(queue: string, maxRetries?: number): QueueJob[];
     retryFailed?(queue: string, maxRetries?: number): number;
@@ -137,7 +143,19 @@ export declare class Queue {
      */
     process(handler: (job: QueueJob | QueueJob[]) => Promise<void> | void, options?: ProcessOptions): void;
     /**
-     * Count jobs filtered by status. Defaults to "pending".
+     * Count jobs by status. Defaults to "pending".
+     *
+     * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+     * but-attempted ones, because they live in the pending queue under the
+     * auto-retry lifecycle (see failed()).
+     * ``"reserved"`` counts jobs a consumer has popped but not yet
+     * completed/failed (in-flight against the visibility timeout).
+     * ``"completed"`` counts jobs the consumer has finished successfully.
+     * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+     * the dead-letter store -- jobs whose attempts >= maxRetries and that
+     * have given up. Use deadLetters() to list them. Retryable-but-attempted
+     * jobs are NOT counted by size("failed"); use failed() to list them or
+     * size("pending") to include them in a total.
      */
     size(status?: string): number;
     /**
@@ -172,7 +190,11 @@ export declare class Queue {
     /**
      * Get jobs that failed at least once but are still being retried
      * (0 < attempts < maxRetries). These live in the pending queue under the
-     * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+     * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+     * count and a retryBackoff delay) so pop() picks them up again. They are
+     * NOT counted by size("failed") -- that alias counts the dead-letter store,
+     * matching deadLetters(). To include retryable-failed jobs in a total, use
+     * size("pending"). Terminal failures are returned by deadLetters().
      */
     failed(): QueueJob[];
     /**
@@ -184,7 +206,22 @@ export declare class Queue {
      */
     retry(jobId?: string, delaySeconds?: number): boolean;
     /**
-     * Get dead letter jobs — failed jobs that exceeded max retries.
+     * Get jobs that exceeded max_retries -- terminal failures.
+     *
+     * Same set counted by size("failed") / size("dead") / size("dead_letter")
+     * (three aliases for the dead-letter store). To LIST retryable-but-
+     * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+     * being auto-retried, use failed() -- those live in the pending queue and
+     * are NOT dead letters.
+     *
+     * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+     * so callers can iterate uniformly with the rest of the queue API and, in
+     * particular, call ``.retry()`` on each to manually revive it:
+     *
+     *     for (const job of queue.deadLetters()) {
+     *       Log.warn(`revived ${job.id}: ${job.error}`);
+     *       job.retry();
+     *     }
      */
     deadLetters(maxRetries?: number): QueueJob[];
     /**

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -122,7 +122,13 @@ export declare class LiteBackend {
      * Explicit re-queue requested by the caller (job.retry()).
      *
      * Always re-enqueues regardless of the retry limit — manual override,
-     * distinct from the automatic failJob() path.
+     * distinct from the automatic failJob() path. Cleans up BOTH the
+     * reservation record AND any dead-letter file for this id, so a caller
+     * that iterates deadLetters() and calls .retry() on each doesn't leave
+     * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+     * Aligns with retry(queue, jobId) which had always unlinked the
+     * dead-letter file -- two spellings of the same intent that previously
+     * diverged.
      */
     retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
 }

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -87,8 +87,13 @@ export declare class MongoBackend implements QueueBackend {
      * retries remain, else dead-letter. Mirrors the file/lite backend.
      */
     fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff?: number): void;
-    /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
-    retry(queue: string, id: string, delaySeconds?: number): void;
+    /**
+     * Revive a specific dead-letter job by id. Returns true if the DL was found
+     * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+     * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+     * and Queue.retry(id) reported success for every call, even for unknown ids.
+     */
+    retry(queue: string, id: string, delaySeconds?: number): boolean;
     /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
     deadLetters(queue: string, maxRetries?: number): QueueJob[];
     /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */

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

@@ -0,0 +1,55 @@
+import type { Router } from "./router.js";
+export declare class SsoError extends Error {
+}
+type Json = Record<string, any>;
+export interface SsoOptions {
+    issuer?: string;
+    clientId?: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    scopes?: string[];
+    verify?: "introspection" | "jwks";
+    postLogoutRedirectUri?: string;
+    claimMap?: Record<string, string>;
+    timeout?: number;
+}
+export declare class Sso {
+    static readonly PENDING_KEY = "_tina4_sso_pending";
+    static readonly SESSION_KEY = "_tina4_sso";
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly redirectUri: string;
+    readonly scopes: string[];
+    readonly verify: "introspection" | "jwks";
+    readonly postLogoutRedirectUri?: string;
+    readonly claimMap: Record<string, string>;
+    readonly timeout: number;
+    private metadata;
+    private static mountedRouters;
+    constructor(options?: SsoOptions);
+    static fromIssuer(options?: SsoOptions): Promise<Sso>;
+    static configured(): boolean;
+    private jsonEnv;
+    private static secureUrl;
+    private validateConfig;
+    private requestJson;
+    discover(force?: boolean): Promise<Json>;
+    static safeReturn(value?: string): string;
+    private session;
+    login(requestOrSession: any, returnTo?: string): Promise<string>;
+    private static equal;
+    private static jwtPayload;
+    private introspect;
+    private claim;
+    private normalize;
+    callback(requestOrSession: any, query?: Json): Promise<{
+        identity: Json;
+        return_to: string;
+    }>;
+    identity(requestOrSession: any): Json | null;
+    refresh(requestOrSession: any): Promise<Json>;
+    logout(requestOrSession: any, returnTo?: string): Promise<string>;
+    static mountConfigured(router: Router): Promise<boolean>;
+}
+export { Sso as SSO };

package/types/orm/src/baseModel.d.ts

@@ -271,6 +271,8 @@ export declare class BaseModel {
      * @param case_ Key casing: 'camel' (default, keys as-is) or 'snake' (convert via fieldMapping).
      */
     toDict(include?: string[], case_?: "camel" | "snake"): Record<string, unknown>;
+    toFeature(geometryField?: string, include?: string[]): Record<string, unknown>;
+    static featureCollection(models: BaseModel[], geometryField?: string, include?: string[]): Record<string, unknown>;
     /**
      * Convert to an associative object (alias for toDict).
      */
@@ -302,6 +304,7 @@ export declare class BaseModel {
      * Uses the adapter's createTable method if available, otherwise builds SQL directly.
      */
     static createTable(): Promise<boolean>;
+    private static createSpatialIndexes;
     /**
      * Find a record by primary key or throw an error if not found.
      */
@@ -336,11 +339,16 @@ export declare class BaseModel {
     /**
      * Invalidate every cached query that touches this model's table.
      *
-     * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-     * this table is busted too (it carries this table's tag), while a query that
-     * never touches this table is left intact. Called after every ORM write
-     * (save/delete/forceDelete/restore) so a read-after-write never serves a
-     * stale/deleted row (CACHE-DEC-01).
+     * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+     * this table is busted too because it carries this table's tag; a query
+     * that never touches this table is left intact), then cascaded to the
+     * DB layer on this model's bound connection so an out-of-band write /
+     * deliberate refresh / race-with-another-process cannot leave stale rows
+     * in db.fetch()'s persistent cache. Called after every ORM write
+     * (save/delete/forceDelete/restore) so a read-after-write never serves
+     * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+     * DB-layer cascade -- previously the two cache layers disagreed under
+     * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
      */
     static clearCache(): void;
     /**

package/types/orm/src/index.d.ts

@@ -19,6 +19,8 @@ export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export { Point, SpatialNotSupportedError, DEFAULT_SRID } from "./point.js";
+export type { GeoJsonPoint } from "./point.js";
 export { DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS, CONNECT_TIMEOUT_TOLERANCE_MS, connectTimeoutMillis, driverConnectTimeoutMillis, connectTarget, withConnectTimeout, } from "./connectTimeout.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";

package/types/orm/src/point.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_SRID = 4326;
+export declare class SpatialNotSupportedError extends Error {
+    constructor(message: string);
+}
+export type GeoJsonPoint = {
+    type: "Point";
+    coordinates: [number, number];
+};
+/** Immutable SRID-aware longitude/latitude point (ADR-0057). */
+export declare class Point {
+    readonly lon: number;
+    readonly lat: number;
+    readonly srid: number;
+    constructor(lon: unknown, lat: unknown, srid?: unknown);
+    get wkt(): string;
+    get ewkt(): string;
+    get geojson(): GeoJsonPoint;
+    toJSON(): GeoJsonPoint;
+    toArray(): [number, number];
+    static parse(value: unknown, srid?: number): Point;
+    static geometryBinding(value: unknown, srid?: number): [string, "ewkt" | "geojson"];
+    private static fromGeoJson;
+    private static fromWkb;
+}

package/types/orm/src/queryBuilder.d.ts

@@ -22,6 +22,7 @@ export declare class QueryBuilder {
     private table;
     private db;
     private columns;
+    private selectParams;
     private wheres;
     private params;
     private joinClauses;
@@ -29,6 +30,8 @@ export declare class QueryBuilder {
     private havings;
     private havingParams;
     private orderByCols;
+    private orderByParams;
+    private primaryKey;
     private limitVal;
     private offsetVal;
     /**
@@ -42,7 +45,7 @@ export declare class QueryBuilder {
      * @param db - Optional database adapter.
      * @returns A new QueryBuilder instance.
      */
-    static fromTable(tableName: string, db?: DatabaseAdapter): QueryBuilder;
+    static fromTable(tableName: string, db?: DatabaseAdapter, primaryKey?: string): QueryBuilder;
     /**
      * Set the columns to select.
      *
@@ -104,6 +107,11 @@ export declare class QueryBuilder {
      * @returns this for chaining.
      */
     orderBy(expression: string): QueryBuilder;
+    withinDistance(column: string, pointValue: unknown, radiusMetres: number, srid?: number): QueryBuilder;
+    intersects(column: string, geometry: unknown, srid?: number): QueryBuilder;
+    bbox(column: string, minLon: unknown, minLat: unknown, maxLon: unknown, maxLat: unknown, srid?: number): QueryBuilder;
+    selectDistance(column: string, pointValue: unknown, alias?: string, srid?: number): QueryBuilder;
+    orderByDistance(column: string, pointValue: unknown, direction?: "ASC" | "DESC", srid?: number): QueryBuilder;
     /**
      * Set LIMIT and optional OFFSET.
      *
@@ -190,4 +198,5 @@ export declare class QueryBuilder {
      * Ensure a database adapter is available.
      */
     private ensureDb;
+    private engine;
 }

package/types/orm/src/sqlTranslator.d.ts

@@ -17,6 +17,19 @@
  * Also includes a query cache with TTL support.
  */
 export declare class SQLTranslator {
+    private static readonly SPATIAL_ENGINES;
+    private static readonly SPATIAL_IDENTIFIER;
+    static requireSpatial(engine: string, feature: string): string;
+    static spatialIdentifier(name: string, what?: string): string;
+    static pointColumnType(engine: string, srid?: number): string;
+    static spatialIndex(engine: string, table: string, column: string): string;
+    static pointLiteral(engine: string, srid?: number): string;
+    static withinDistance(engine: string, column: string, srid?: number): string;
+    static distance(engine: string, column: string, srid?: number): string;
+    static distanceAs(engine: string, column: string, alias: string, srid?: number): string;
+    static geometryLiteral(engine: string, form: "ewkt" | "geojson", srid?: number): string;
+    static intersects(engine: string, column: string, form?: "ewkt" | "geojson", srid?: number): string;
+    static bbox(engine: string, column: string, srid?: number): string;
     /**
      * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
      *

package/types/orm/src/types.d.ts

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey" | "point";
 export interface FieldDefinition {
     type: FieldType;
     primaryKey?: boolean;
@@ -23,6 +23,10 @@ export interface FieldDefinition {
     references?: string;
     /** For type "foreignKey": override the has-many property name on the referenced model */
     relatedName?: string;
+    /** For type "point": spatial reference id (default WGS 84 / 4326). */
+    srid?: number;
+    /** For type "point": create the provider's spatial index (default true). */
+    spatialIndex?: boolean;
 }
 export interface RelationshipDefinition {
     model: string;