tetherdb 0.1.0

package/dist/server/server.d.ts

@@ -0,0 +1,206 @@
+import * as http from 'node:http';
+import { WebSocketServer } from 'ws';
+import type { Storage, UserStorage } from './storage/index.js';
+import { Sync } from './sync.js';
+/**
+ * Rate limiting and resource control options for authentication endpoints and sync streams.
+ */
+export interface RateLimitOptions {
+    /** Maximum login attempts per IP within the time window (defaults to 100). */
+    ipLoginMaxRequests?: number;
+    /** Maximum login attempts per target username within the time window (defaults to 20). */
+    userLoginMaxRequests?: number;
+    /** Maximum registration attempts per IP within the time window (defaults to 100). */
+    ipRegisterMaxRequests?: number;
+    /** Maximum WebSocket connection handshakes per IP within the time window (defaults to 100). */
+    ipSyncMaxRequests?: number;
+    /** Maximum concurrent active WebSocket connections allowed per user channel (defaults to 20). */
+    maxConcurrentConnectionsPerUser?: number;
+    /** Maximum duration in milliseconds to wait for authentication before terminating socket (defaults to 10,000ms). */
+    authTimeoutMs?: number;
+    /** Sliding window duration in milliseconds (defaults to 60,000ms / 1 minute). */
+    windowMs?: number;
+    /** Consecutive failed attempts before progressive backoff begins (defaults to 5). */
+    maxFailures?: number;
+    /** Initial backoff duration in milliseconds (defaults to 1,000ms). */
+    initialBackoffMs?: number;
+    /** Maximum backoff duration in milliseconds (defaults to 900,000ms / 15 minutes). */
+    maxBackoffMs?: number;
+}
+/**
+ * Options for configuring Cross-Origin Resource Sharing (CORS) on HTTP endpoints.
+ */
+export interface CorsOptions {
+    /**
+     * Allowed origin(s). Can be `'*'` for unrestricted access, a specific origin string (e.g. `'https://example.com'`),
+     * an array of allowed origin strings, `true` to reflect the request's `Origin` header, or `false` to disable CORS headers.
+     * Defaults to `'*'`.
+     */
+    origin?: string | string[] | boolean;
+    /** Whether to set `Access-Control-Allow-Credentials: true` (defaults to false). */
+    credentials?: boolean;
+    /** Allowed request headers for preflight OPTIONS checks (defaults to `['Content-Type', 'Authorization']`). */
+    allowedHeaders?: string[];
+    /** Exposed response headers (Access-Control-Expose-Headers). */
+    exposedHeaders?: string[];
+    /** Maximum age in seconds to cache preflight responses (Access-Control-Max-Age). */
+    maxAge?: number;
+}
+/**
+ * Pluggable logger interface for TetherServer logging.
+ */
+export interface TetherLogger {
+    /** Logs debug information. */
+    debug(message: string, ...args: unknown[]): void;
+    /** Logs operational information. */
+    info(message: string, ...args: unknown[]): void;
+    /** Logs warning conditions. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Logs error conditions. */
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Configuration options for the TetherServer.
+ */
+export interface TetherServerOptions {
+    /** Custom storage instance. Defaults to MemoryStorage if not defined. */
+    storage?: Storage;
+    /** Base path for HTTP REST endpoints (defaults to ''). */
+    basePath?: string;
+    /** Path for WebSocket upgrade requests (defaults to '/sync'). */
+    webSocketPath?: string;
+    /** Whether user self-registration is allowed via `/auth/register` (defaults to true). */
+    allowRegistration?: boolean;
+    /** Rate limiting options for auth and sync endpoints, or `false` to disable rate limiting (defaults to true). */
+    rateLimiting?: boolean | RateLimitOptions;
+    /** Whether to trust the `X-Forwarded-For` header for resolving client IP addresses (defaults to false). */
+    trustProxy?: boolean;
+    /** CORS options for HTTP endpoints, `false` to disable CORS headers, or `true` for default permissive CORS (defaults to true). */
+    cors?: boolean | CorsOptions;
+    /** Optional custom logger instance, or `false` to silence internal server logs (defaults to `console`). */
+    logger?: TetherLogger | false;
+}
+/**
+ * Options for starting the standard server launcher.
+ */
+export interface StartServerOptions extends TetherServerOptions {
+    /** Port number to bind (defaults to 8080 or PORT environment variable). */
+    port?: number;
+    /** Host interface to bind (defaults to '0.0.0.0'). */
+    host?: string;
+}
+/**
+ * Result returned when launching a server using `startServer()`.
+ */
+export interface RunningServer {
+    /** The TetherServer instance. */
+    server: TetherServer;
+    /** The running Node.js HTTP server instance. */
+    httpServer: http.Server;
+    /** Bound port number. */
+    port: number;
+    /** Bound host address. */
+    host: string;
+    /** Closes both HTTP and WebSocket server cleanly. */
+    close(): Promise<void>;
+}
+/**
+ * Starts a complete standalone HTTP & WebSocket synchronization server.
+ *
+ * @param options - Start options including port, host, storage, and limits.
+ * @returns Handle to the running server.
+ */
+export declare function startServer(options?: StartServerOptions): Promise<RunningServer>;
+/**
+ * Unified HTTP and WebSocket server handling authentication endpoints (`/auth/register`, `/auth/login`)
+ * and real-time streaming connections (`/sync`).
+ */
+export declare class TetherServer {
+    /** Underlying storage engine for users, apps, and tables. */
+    readonly storage: Storage;
+    /** Real-time synchronization connection and broadcast coordinator. */
+    readonly sync: Sync;
+    /** Base path for HTTP REST endpoints. */
+    readonly basePath: string;
+    /** Path for WebSocket upgrade requests. */
+    readonly webSocketPath: string;
+    readonly trustProxy: boolean;
+    private readonly allowRegistration;
+    private readonly corsConfig;
+    private readonly logger;
+    private readonly ipLoginLimiter;
+    private readonly userLoginLimiter;
+    private readonly ipRegisterLimiter;
+    private _httpServer;
+    private _webSocketServer;
+    private lockHandle;
+    /**
+     * Initializes a new TetherServer instance.
+     *
+     * @param options - Configuration options for storage, endpoints, and rate limiting.
+     */
+    constructor(options?: TetherServerOptions);
+    /**
+     * Active Node.js HTTP server instance, or `null` if not listening.
+     */
+    get httpServer(): http.Server | null;
+    /**
+     * Active WebSocketServer instance, or `null` if not listening.
+     */
+    get webSocketServer(): WebSocketServer | null;
+    /**
+     * Declares an application and its tables.
+     * Registers the application and any declared tables if not already present.
+     *
+     * @param appId - Application identifier.
+     * @param tables - Array of table names.
+     */
+    declareApp(appId: string, tables?: string[]): Promise<void>;
+    /**
+     * Declares a user account with the specified username and password.
+     * Creates the user if not already registered, or updates the existing user's password.
+     *
+     * @param username - Username for the account.
+     * @param password - Plaintext password for the account.
+     * @returns UserStorage handle for the declared user.
+     */
+    declareUser(username: string, password: string): Promise<UserStorage>;
+    /**
+     * Attaches WebSocket synchronization handling to an existing HTTP server.
+     *
+     * @param server - The HTTP server instance to attach to.
+     */
+    attach(server: http.Server): void;
+    /**
+     * Starts the HTTP and WebSocket server listening on the specified port and host.
+     *
+     * @param port - Port number to bind. Defaults to 8080.
+     * @param host - Host interface to bind. Defaults to '0.0.0.0'.
+     * @returns The active Node.js HTTP server instance.
+     */
+    listen(port?: number, host?: string): Promise<http.Server>;
+    /**
+     * Closes active HTTP server and WebSocket server listeners.
+     */
+    close(): Promise<void>;
+    /**
+     * Handles incoming HTTP requests for authentication and discovery endpoints.
+     *
+     * @param req - Incoming HTTP request.
+     * @param res - Server HTTP response.
+     * @returns `true` if the request was handled by TetherDB; `false` if the path did not match.
+     */
+    handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<boolean>;
+    private getCorsHeaders;
+    private sendJson;
+    private readJsonBody;
+    private handleOptions;
+    private handleHealth;
+    private handleReady;
+    private handleMetrics;
+    private handleRegister;
+    private handleLogin;
+    private readCredentials;
+    private getClientIp;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"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"}

package/dist/server/storage/app.d.cts

@@ -0,0 +1,70 @@
+import type { ChangeRecord } from '../../shared/types.cjs';
+import type { TableStorage } from './table.cjs';
+import type { UserStorage } from './user.cjs';
+/**
+ * Application namespace storage managing tables, batch changelogs, and user sequence counters.
+ */
+export interface AppStorage {
+    /** Application namespace identifier. */
+    readonly id: string;
+    /**
+     * Creates/registers a new table within this application.
+     * Throws an error if a table with the specified name already exists.
+     *
+     * @param name - Name of the table.
+     * @returns Created TableStorage handle.
+     * @throws Error if the table already exists.
+     */
+    createTable(name: string): Promise<TableStorage>;
+    /**
+     * Retrieves a table handle if it exists.
+     *
+     * @param name - Name of the table.
+     * @returns TableStorage handle or `undefined`.
+     */
+    getTable(name: string): Promise<TableStorage | undefined>;
+    /**
+     * Lists all registered tables in this application.
+     *
+     * @returns Array of TableStorage handles.
+     */
+    getTables(): Promise<TableStorage[]>;
+    /**
+     * Applies an array of mutation changes for a user applying LWW conflict resolution,
+     * assigning sequential change numbers, and appending to the changelog.
+     *
+     * @param user - Target user handle.
+     * @param changes - Array of change records.
+     * @returns Applied changes with assigned sequence numbers and new sequence number.
+     */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /**
+     * Retrieves change operations for a user since a given sequence number within this app.
+     *
+     * @param user - Target user handle.
+     * @param fromSeq - Starting sequence number (exclusive).
+     * @returns Changes, current sequence, and snapshot requirement flag.
+     */
+    getChangesSince(user: UserStorage, fromSeq: number): Promise<{
+        changes: ChangeRecord[];
+        currentSeq: number;
+        requiresSnapshot?: boolean;
+    }>;
+    /**
+     * Returns the current global sequence number for a user within this application.
+     *
+     * @param user - Target user handle.
+     * @returns Current integer sequence number.
+     */
+    getCurrentSeq(user: UserStorage): Promise<number>;
+    /**
+     * Deletes this entire application and all associated data across all users and tables.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/server/storage/app.d.ts

@@ -0,0 +1,70 @@
+import type { ChangeRecord } from '../../shared/types.js';
+import type { TableStorage } from './table.js';
+import type { UserStorage } from './user.js';
+/**
+ * Application namespace storage managing tables, batch changelogs, and user sequence counters.
+ */
+export interface AppStorage {
+    /** Application namespace identifier. */
+    readonly id: string;
+    /**
+     * Creates/registers a new table within this application.
+     * Throws an error if a table with the specified name already exists.
+     *
+     * @param name - Name of the table.
+     * @returns Created TableStorage handle.
+     * @throws Error if the table already exists.
+     */
+    createTable(name: string): Promise<TableStorage>;
+    /**
+     * Retrieves a table handle if it exists.
+     *
+     * @param name - Name of the table.
+     * @returns TableStorage handle or `undefined`.
+     */
+    getTable(name: string): Promise<TableStorage | undefined>;
+    /**
+     * Lists all registered tables in this application.
+     *
+     * @returns Array of TableStorage handles.
+     */
+    getTables(): Promise<TableStorage[]>;
+    /**
+     * Applies an array of mutation changes for a user applying LWW conflict resolution,
+     * assigning sequential change numbers, and appending to the changelog.
+     *
+     * @param user - Target user handle.
+     * @param changes - Array of change records.
+     * @returns Applied changes with assigned sequence numbers and new sequence number.
+     */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /**
+     * Retrieves change operations for a user since a given sequence number within this app.
+     *
+     * @param user - Target user handle.
+     * @param fromSeq - Starting sequence number (exclusive).
+     * @returns Changes, current sequence, and snapshot requirement flag.
+     */
+    getChangesSince(user: UserStorage, fromSeq: number): Promise<{
+        changes: ChangeRecord[];
+        currentSeq: number;
+        requiresSnapshot?: boolean;
+    }>;
+    /**
+     * Returns the current global sequence number for a user within this application.
+     *
+     * @param user - Target user handle.
+     * @returns Current integer sequence number.
+     */
+    getCurrentSeq(user: UserStorage): Promise<number>;
+    /**
+     * Deletes this entire application and all associated data across all users and tables.
+     *
+     * @returns True if deleted successfully.
+     */
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/server/storage/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/server/storage/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAE1D;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAErC;;;;;;;OAOG;IACH,YAAY,CACV,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,eAAe,CACb,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,OAAO,EAAE,YAAY,EAAE,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC,CAAC;IAEH;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElD;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B"}

package/dist/server/storage/base/app.d.cts

@@ -0,0 +1,42 @@
+import { type ChangeRecord, type StoredRecord } from '../../../shared/types.cjs';
+import type { AppStorage } from '../app.cjs';
+import type { TableStorage } from '../table.cjs';
+import type { UserStorage } from '../user.cjs';
+/**
+ * Common abstract base class for AppStorage implementations.
+ */
+export declare abstract class AppBaseStorage implements AppStorage {
+    readonly id: string;
+    constructor(id: string);
+    /** Creates/registers a new table within this application. */
+    abstract createTable(name: string): Promise<TableStorage>;
+    /** Retrieves a table handle if it exists. */
+    abstract getTable(name: string): Promise<TableStorage | undefined>;
+    /** Lists all registered tables in this application. */
+    abstract getTables(): Promise<TableStorage[]>;
+    /** Applies batch mutation changes for a user. */
+    abstract applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /** Retrieves changes for a user since a given sequence number. */
+    abstract getChangesSince(user: UserStorage, fromSeq: number): Promise<{
+        changes: ChangeRecord[];
+        currentSeq: number;
+        requiresSnapshot?: boolean;
+    }>;
+    /** Returns the current global sequence number for a user within this application. */
+    abstract getCurrentSeq(user: UserStorage): Promise<number>;
+    /** Deletes this entire application and all associated data. */
+    abstract delete(): Promise<boolean>;
+}
+/**
+ * Applies a change to an existing (or undefined) record and assigns the sequence number.
+ */
+export declare function applyChangeToRecord(change: ChangeRecord, existing: StoredRecord | undefined, seq: number): {
+    updatedRecord: StoredRecord;
+    appliedChange: ChangeRecord & {
+        seq: number;
+    };
+};
+//# sourceMappingURL=app.d.ts.map

package/dist/server/storage/base/app.d.ts

@@ -0,0 +1,42 @@
+import { type ChangeRecord, type StoredRecord } from '../../../shared/types.js';
+import type { AppStorage } from '../app.js';
+import type { TableStorage } from '../table.js';
+import type { UserStorage } from '../user.js';
+/**
+ * Common abstract base class for AppStorage implementations.
+ */
+export declare abstract class AppBaseStorage implements AppStorage {
+    readonly id: string;
+    constructor(id: string);
+    /** Creates/registers a new table within this application. */
+    abstract createTable(name: string): Promise<TableStorage>;
+    /** Retrieves a table handle if it exists. */
+    abstract getTable(name: string): Promise<TableStorage | undefined>;
+    /** Lists all registered tables in this application. */
+    abstract getTables(): Promise<TableStorage[]>;
+    /** Applies batch mutation changes for a user. */
+    abstract applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+    /** Retrieves changes for a user since a given sequence number. */
+    abstract getChangesSince(user: UserStorage, fromSeq: number): Promise<{
+        changes: ChangeRecord[];
+        currentSeq: number;
+        requiresSnapshot?: boolean;
+    }>;
+    /** Returns the current global sequence number for a user within this application. */
+    abstract getCurrentSeq(user: UserStorage): Promise<number>;
+    /** Deletes this entire application and all associated data. */
+    abstract delete(): Promise<boolean>;
+}
+/**
+ * Applies a change to an existing (or undefined) record and assigns the sequence number.
+ */
+export declare function applyChangeToRecord(change: ChangeRecord, existing: StoredRecord | undefined, seq: number): {
+    updatedRecord: StoredRecord;
+    appliedChange: ChangeRecord & {
+        seq: number;
+    };
+};
+//# sourceMappingURL=app.d.ts.map

package/dist/server/storage/base/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/server/storage/base/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EAEjB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,8BAAsB,cAAe,YAAW,UAAU;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,YAAY,EAAE,EAAE,MAAM,EAErB;IAED,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAE1D,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAEnE,uDAAuD;IACvD,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE9C,iDAAiD;IACjD,QAAQ,CAAC,YAAY,CACnB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAExD,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CACtB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,OAAO,EAAE,YAAY,EAAE,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC,CAAC;IAEH,qFAAqF;IACrF,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE3D,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,GAAG,SAAS,EAClC,GAAG,EAAE,MAAM,GACV;IACD,aAAa,EAAE,YAAY,CAAC;IAC5B,aAAa,EAAE,YAAY,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,CAyBA"}

package/dist/server/storage/base/index.d.cts

@@ -0,0 +1,5 @@
+export { AppBaseStorage, applyChangeToRecord } from './app.cjs';
+export { BaseStorage, buildAppSummaries, filterTargetApps, } from './storage.cjs';
+export { filterActiveRecords, TableBaseStorage, targetChangesForTable, } from './table.cjs';
+export { hashUserPassword, UserBaseStorage, verifyUserPassword, } from './user.cjs';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/storage/base/index.d.ts

@@ -0,0 +1,5 @@
+export { AppBaseStorage, applyChangeToRecord } from './app.js';
+export { BaseStorage, buildAppSummaries, filterTargetApps, } from './storage.js';
+export { filterActiveRecords, TableBaseStorage, targetChangesForTable, } from './table.js';
+export { hashUserPassword, UserBaseStorage, verifyUserPassword, } from './user.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/storage/base/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/storage/base/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,WAAW,CAAC"}

package/dist/server/storage/base/storage.d.cts

@@ -0,0 +1,40 @@
+import type { AppStorage } from '../app.cjs';
+import type { MaintenanceResult, Storage, StorageOptions, StorageStatus } from '../storage.cjs';
+import type { UserStorage } from '../user.cjs';
+/**
+ * Common abstract base class for Storage implementations.
+ */
+export declare abstract class BaseStorage implements Storage {
+    readonly options?: StorageOptions;
+    constructor(options?: StorageOptions);
+    /** Backend persistence type name ('file', 'memory', 'sqlite'). */
+    abstract readonly backend: string;
+    /** Secret key used for signing session tokens. */
+    abstract readonly secret: string;
+    /** Optional storage base directory if disk-backed. */
+    protected getBaseDir(): string | undefined;
+    abstract createApp(id: string): Promise<AppStorage>;
+    abstract getApp(id: string): Promise<AppStorage | undefined>;
+    abstract getApps(): Promise<AppStorage[]>;
+    abstract createUser(username: string, password: string): Promise<UserStorage>;
+    abstract getUser(id: string): Promise<UserStorage | undefined>;
+    abstract getUserByUsername(username: string): Promise<UserStorage | undefined>;
+    abstract getUsers(): Promise<UserStorage[]>;
+    abstract checkpoint(appId?: string): Promise<MaintenanceResult>;
+    abstract vacuum(appId?: string): Promise<MaintenanceResult>;
+    abstract prune(appId?: string, keepCount?: number): Promise<MaintenanceResult>;
+    getUserByToken(token: string): Promise<UserStorage | undefined>;
+    getStatus(appId?: string): Promise<StorageStatus>;
+}
+/**
+ * Filters the list of applications by an optional target appId, validating format and existence.
+ */
+export declare function filterTargetApps(allApps: AppStorage[], appId?: string): AppStorage[];
+/**
+ * Builds array of application summaries including their table names.
+ */
+export declare function buildAppSummaries(apps: AppStorage[]): Promise<Array<{
+    id: string;
+    tables: string[];
+}>>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/server/storage/base/storage.d.ts

@@ -0,0 +1,40 @@
+import type { AppStorage } from '../app.js';
+import type { MaintenanceResult, Storage, StorageOptions, StorageStatus } from '../storage.js';
+import type { UserStorage } from '../user.js';
+/**
+ * Common abstract base class for Storage implementations.
+ */
+export declare abstract class BaseStorage implements Storage {
+    readonly options?: StorageOptions;
+    constructor(options?: StorageOptions);
+    /** Backend persistence type name ('file', 'memory', 'sqlite'). */
+    abstract readonly backend: string;
+    /** Secret key used for signing session tokens. */
+    abstract readonly secret: string;
+    /** Optional storage base directory if disk-backed. */
+    protected getBaseDir(): string | undefined;
+    abstract createApp(id: string): Promise<AppStorage>;
+    abstract getApp(id: string): Promise<AppStorage | undefined>;
+    abstract getApps(): Promise<AppStorage[]>;
+    abstract createUser(username: string, password: string): Promise<UserStorage>;
+    abstract getUser(id: string): Promise<UserStorage | undefined>;
+    abstract getUserByUsername(username: string): Promise<UserStorage | undefined>;
+    abstract getUsers(): Promise<UserStorage[]>;
+    abstract checkpoint(appId?: string): Promise<MaintenanceResult>;
+    abstract vacuum(appId?: string): Promise<MaintenanceResult>;
+    abstract prune(appId?: string, keepCount?: number): Promise<MaintenanceResult>;
+    getUserByToken(token: string): Promise<UserStorage | undefined>;
+    getStatus(appId?: string): Promise<StorageStatus>;
+}
+/**
+ * Filters the list of applications by an optional target appId, validating format and existence.
+ */
+export declare function filterTargetApps(allApps: AppStorage[], appId?: string): AppStorage[];
+/**
+ * Builds array of application summaries including their table names.
+ */
+export declare function buildAppSummaries(apps: AppStorage[]): Promise<Array<{
+    id: string;
+    tables: string[];
+}>>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/server/storage/base/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../../src/server/storage/base/storage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EACV,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,8BAAsB,WAAY,YAAW,OAAO;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAElC,YAAY,OAAO,CAAC,EAAE,cAAc,EAEnC;IAED,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAElC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAEjC,sDAAsD;IACtD,SAAS,CAAC,UAAU,IAAI,MAAM,GAAG,SAAS,CAEzC;IAED,QAAQ,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAC7D,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC/D,QAAQ,CAAC,iBAAiB,CACxB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IACpC,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5D,QAAQ,CAAC,KAAK,CACZ,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAExB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAIpE;IAEK,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAiBtD;CACF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,UAAU,EAAE,CAad;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAAE,GACjB,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAUlD"}

package/dist/server/storage/base/table.d.cts

@@ -0,0 +1,32 @@
+import type { ChangeRecord, SnapshotRecord, StoredRecord } from '../../../shared/types.cjs';
+import type { AppStorage } from '../app.cjs';
+import type { TableStorage } from '../table.cjs';
+import type { UserStorage } from '../user.cjs';
+/**
+ * Common abstract base class for TableStorage implementations.
+ */
+export declare abstract class TableBaseStorage implements TableStorage {
+    readonly name: string;
+    readonly app: AppStorage;
+    constructor(name: string, app: AppStorage);
+    /** Retrieves a single record for a user. */
+    abstract getRecord(user: UserStorage, id: string): Promise<StoredRecord | undefined>;
+    /** Retrieves all active records in this table for a user. */
+    abstract getAllRecords(user: UserStorage): Promise<SnapshotRecord[]>;
+    /** Deletes this table and its data. */
+    abstract delete(): Promise<boolean>;
+    /** Applies batch mutation changes to this table. */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+}
+/**
+ * Filters non-deleted records and attaches table name for snapshot responses.
+ */
+export declare function filterActiveRecords(tableName: string, records: Iterable<StoredRecord>): SnapshotRecord[];
+/**
+ * Targets generic changes with table name and app ID.
+ */
+export declare function targetChangesForTable(tableName: string, appId: string, changes: ChangeRecord[]): ChangeRecord[];
+//# sourceMappingURL=table.d.ts.map

package/dist/server/storage/base/table.d.ts

@@ -0,0 +1,32 @@
+import type { ChangeRecord, SnapshotRecord, StoredRecord } from '../../../shared/types.js';
+import type { AppStorage } from '../app.js';
+import type { TableStorage } from '../table.js';
+import type { UserStorage } from '../user.js';
+/**
+ * Common abstract base class for TableStorage implementations.
+ */
+export declare abstract class TableBaseStorage implements TableStorage {
+    readonly name: string;
+    readonly app: AppStorage;
+    constructor(name: string, app: AppStorage);
+    /** Retrieves a single record for a user. */
+    abstract getRecord(user: UserStorage, id: string): Promise<StoredRecord | undefined>;
+    /** Retrieves all active records in this table for a user. */
+    abstract getAllRecords(user: UserStorage): Promise<SnapshotRecord[]>;
+    /** Deletes this table and its data. */
+    abstract delete(): Promise<boolean>;
+    /** Applies batch mutation changes to this table. */
+    applyChanges(user: UserStorage, changes: ChangeRecord[]): Promise<{
+        applied: ChangeRecord[];
+        newSeq: number;
+    }>;
+}
+/**
+ * Filters non-deleted records and attaches table name for snapshot responses.
+ */
+export declare function filterActiveRecords(tableName: string, records: Iterable<StoredRecord>): SnapshotRecord[];
+/**
+ * Targets generic changes with table name and app ID.
+ */
+export declare function targetChangesForTable(tableName: string, appId: string, changes: ChangeRecord[]): ChangeRecord[];
+//# sourceMappingURL=table.d.ts.map

package/dist/server/storage/base/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../../src/server/storage/base/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,8BAAsB,gBAAiB,YAAW,YAAY;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB,YAAY,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAGxC;IAED,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAChB,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAErC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAErE,uCAAuC;IACvC,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpC,oDAAoD;IAC9C,YAAY,CAChB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,YAAY,EAAE,GACtB,OAAO,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAKtD;CACF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,GAC9B,cAAc,EAAE,CAWlB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EAAE,GACtB,YAAY,EAAE,CAMhB"}