@bluecopa/core 0.1.55 → 0.1.56

package/dist/input-table-db/collectionRef.d.ts

@@ -0,0 +1,24 @@
+import { RxCollection } from 'rxdb';
+import { RxReplicationState } from 'rxdb/plugins/replication';
+import { IWebsocketProvider } from '../config';
+import { Row, WhereOp, CollectionRef, QueryBuilder, InputTableColumn } from './types';
+import { DocRefImpl } from './docRef';
+export declare class CollectionRefImpl<TRow extends Row = Row> implements CollectionRef<TRow> {
+    private collection;
+    private solutionId;
+    private tableName;
+    private primaryKeyField;
+    private pkColumn;
+    private replicationState;
+    private getWebsocketProvider;
+    constructor(collection: RxCollection, solutionId: string, tableName: string, primaryKeyField: string, pkColumn: InputTableColumn | undefined, replicationState: RxReplicationState<any, any>, getWebsocketProvider: () => IWebsocketProvider | undefined);
+    where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
+    orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
+    limit(count: number): QueryBuilder<TRow>;
+    skip(count: number): QueryBuilder<TRow>;
+    doc(id: string): DocRefImpl<TRow>;
+    add(data: Partial<TRow>): Promise<string>;
+    subscribe(callback: (rows: TRow[]) => void): () => void;
+    get(): Promise<TRow[]>;
+    count(callback: (count: number) => void): () => void;
+}

package/dist/input-table-db/docRef.d.ts

@@ -0,0 +1,16 @@
+import { RxCollection } from 'rxdb';
+import { IWebsocketProvider } from '../config';
+import { Row, DocRef } from './types';
+export declare class DocRefImpl<TRow extends Row = Row> implements DocRef<TRow> {
+    private collection;
+    private id;
+    private solutionId;
+    private tableName;
+    private primaryKeyField;
+    private websocketProvider;
+    constructor(collection: RxCollection, id: string, solutionId: string, tableName: string, primaryKeyField: string, websocketProvider: () => IWebsocketProvider | undefined);
+    get(): Promise<TRow | null>;
+    update(data: Partial<TRow>): Promise<void>;
+    delete(): Promise<void>;
+    onSnapshot(callback: (doc: TRow | null) => void): () => void;
+}

package/dist/input-table-db/index.d.ts

@@ -0,0 +1,4 @@
+export { copaInputTableDb } from './inputTableDb';
+export { InputTableColumnType } from './types';
+export { InputTableError } from './utils';
+export type { Row, WhereOp, QueryBuilder, DocRef, CollectionRef, InputTableDB, InputTableDefinition, InputTableColumn } from './types';

package/dist/input-table-db/inputTableDb.d.ts

@@ -0,0 +1,2 @@
+import { InputTableDB } from './types';
+export declare const copaInputTableDb: InputTableDB;

package/dist/input-table-db/queryBuilder.d.ts

@@ -0,0 +1,27 @@
+import { RxCollection } from 'rxdb';
+import { Row, WhereOp, QueryBuilder } from './types';
+type WhereClause = {
+    field: string;
+    op: WhereOp;
+    value: unknown;
+};
+type OrderClause = {
+    field: string;
+    direction: 'asc' | 'desc';
+};
+export declare class QueryBuilderImpl<TRow extends Row = Row> implements QueryBuilder<TRow> {
+    private collection;
+    private wheres;
+    private orders;
+    private limitCount;
+    private skipCount;
+    constructor(collection: RxCollection, initialWhere?: WhereClause, initialOrder?: OrderClause, initialLimit?: number, initialSkip?: number);
+    where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
+    orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
+    limit(count: number): QueryBuilder<TRow>;
+    skip(count: number): QueryBuilder<TRow>;
+    subscribe(callback: (rows: TRow[]) => void): () => void;
+    get(): Promise<TRow[]>;
+    private buildQuery;
+}
+export {};

package/dist/input-table-db/realtimeBinding.d.ts

@@ -0,0 +1,16 @@
+import { RxReplicationState } from 'rxdb/plugins/replication';
+import { IWebsocketProvider } from '../config';
+export type RealtimeBindingHandle = {
+    cleanup: () => void;
+};
+/**
+ * Bind IWebsocketProvider change notifications to RxDB replication.
+ *
+ * Backend publishes events on channel: public-input-table-v2-{workspaceId}-{solutionId}-{tableName}
+ * Events: INSERT, UPDATE, DELETE (one event per operation type)
+ * Payload: { event_name: string, event_type: "INSERT"|"UPDATE"|"DELETE", schema: string }
+ *
+ * Since the payload contains no row data, we trigger reSync() on any change
+ * to re-pull from the server.
+ */
+export declare function createRealtimeBinding(provider: IWebsocketProvider, replicationState: RxReplicationState<any, any>, workspaceId: string, solutionId: string, tableName: string): RealtimeBindingHandle;

package/dist/input-table-db/rxdb/collectionManager.d.ts

@@ -0,0 +1,38 @@
+import { RxCollection } from 'rxdb';
+import { IWebsocketProvider } from '../../config';
+import { InputTableDefinition } from '../types';
+import { ReplicationHandle } from './replication';
+import { RealtimeBindingHandle } from '../realtimeBinding';
+export type ManagedCollection = {
+    collection: RxCollection;
+    replication: ReplicationHandle;
+    realtimeBinding: RealtimeBindingHandle | null;
+    tableName: string;
+    solutionId: string;
+    workspaceId: string;
+    primaryKeyField: string;
+    lastAccessed: number;
+    /** Number of active subscriptions — prevents LRU eviction while > 0 */
+    refCount: number;
+};
+/**
+ * Increment refCount for a managed collection (call when subscribing).
+ */
+export declare function addRef(managed: ManagedCollection): void;
+/**
+ * Decrement refCount for a managed collection (call when unsubscribing).
+ */
+export declare function releaseRef(managed: ManagedCollection): void;
+/**
+ * Get or create an RxDB collection for a table.
+ * Deduplicates concurrent creation requests. Handles LRU eviction with refcount protection.
+ */
+export declare function getOrCreateCollection(solutionId: string, tableDef: InputTableDefinition, workspaceId: string, websocketProvider?: IWebsocketProvider): Promise<ManagedCollection>;
+/**
+ * Close a specific collection and stop its replication.
+ */
+export declare function closeCollection(solutionId: string, tableName: string, workspaceId: string): Promise<void>;
+/**
+ * Close all collections (or all for a specific solutionId).
+ */
+export declare function closeAllCollections(solutionId?: string): Promise<void>;

package/dist/input-table-db/rxdb/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const CHECKPOINT_FIELD = "updated_at";
+/** Maximum open RxDB collections (open-source limit is 16, leave headroom) */
+export declare const MAX_COLLECTIONS = 14;
+/** Replication retry interval (ms) */
+export declare const REPLICATION_RETRY_TIME = 5000;
+/** Replication pull batch size */
+export declare const PULL_BATCH_SIZE = 100;
+/** Replication push batch size */
+export declare const PUSH_BATCH_SIZE = 10;

package/dist/input-table-db/rxdb/database.d.ts

@@ -0,0 +1,3 @@
+import { RxDatabase } from 'rxdb';
+export declare function getInputTableDatabase(): Promise<RxDatabase>;
+export declare function closeInputTableDatabase(): Promise<void>;

package/dist/input-table-db/rxdb/replication.d.ts

@@ -0,0 +1,17 @@
+import { RxReplicationState } from 'rxdb/plugins/replication';
+import { RxCollection } from 'rxdb';
+import { Subject } from 'rxjs';
+type Checkpoint = {
+    id: string;
+    updatedAt: string;
+} | null;
+export type ReplicationHandle = {
+    state: RxReplicationState<any, Checkpoint>;
+    pullStream$: Subject<any>;
+    cancel: () => Promise<void>;
+};
+/**
+ * Set up bidirectional replication between an RxDB collection and PostgREST via BFF.
+ */
+export declare function createReplication(collection: RxCollection, solutionId: string, tableName: string, primaryKeyField: string): ReplicationHandle;
+export {};

package/dist/input-table-db/rxdb/schemaBuilder.d.ts

@@ -0,0 +1,12 @@
+import { RxJsonSchema } from 'rxdb';
+import { InputTableDefinition } from '../types';
+/**
+ * Build an RxDB JSON Schema from an InputTableDefinition.
+ * Adds the checkpoint system column automatically.
+ */
+export declare function buildRxdbSchema(tableDef: InputTableDefinition): RxJsonSchema<any>;
+/**
+ * Convert a table name to a valid RxDB collection name.
+ * RxDB requires: ^[a-z][a-z0-9]*$ (no underscores, no uppercase)
+ */
+export declare function toCollectionName(solutionId: string, tableName: string): string;

package/dist/input-table-db/types.d.ts

@@ -0,0 +1,67 @@
+import { IWebsocketProvider } from '../config';
+export declare enum InputTableColumnType {
+    UUID = "uuid",
+    TEXT = "text",
+    INTEGER = "integer",
+    BIGINT = "bigint",
+    NUMERIC = "numeric",
+    BOOLEAN = "boolean",
+    TIMESTAMPTZ = "timestamptz",
+    DATE = "date",
+    TIME = "time",
+    JSONB = "jsonb"
+}
+export type InputTableColumn = {
+    name: string;
+    type: InputTableColumnType;
+    nullable?: boolean;
+    primary_key?: boolean;
+    auto_increment?: boolean;
+    default?: string | number | boolean | null;
+    searchable?: boolean;
+};
+export type InputTableDefinition = {
+    name: string;
+    columns: InputTableColumn[];
+};
+/** A plain row object returned by the SDK. */
+export type Row = Record<string, unknown>;
+/** Where clause operators */
+export type WhereOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in';
+export interface QueryBuilder<TRow extends Row = Row> {
+    where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
+    orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
+    limit(count: number): QueryBuilder<TRow>;
+    skip(count: number): QueryBuilder<TRow>;
+    subscribe(callback: (rows: TRow[]) => void): () => void;
+    get(): Promise<TRow[]>;
+}
+export interface DocRef<TRow extends Row = Row> {
+    get(): Promise<TRow | null>;
+    update(data: Partial<TRow>): Promise<void>;
+    delete(): Promise<void>;
+    onSnapshot(callback: (doc: TRow | null) => void): () => void;
+}
+export interface CollectionRef<TRow extends Row = Row> {
+    where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
+    orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
+    limit(count: number): QueryBuilder<TRow>;
+    skip(count: number): QueryBuilder<TRow>;
+    doc(id: string): DocRef<TRow>;
+    add(data: Partial<TRow>): Promise<string>;
+    subscribe(callback: (rows: TRow[]) => void): () => void;
+    get(): Promise<TRow[]>;
+    count(callback: (count: number) => void): () => void;
+}
+export interface InputTableDB {
+    collection<TRow extends Row = Row>(name: string): CollectionRef<TRow>;
+    setWebsocketProvider(provider: IWebsocketProvider): void;
+    /** Force-clear the schema cache. Call after schema changes. */
+    clearSchemaCache(): void;
+    destroy(): Promise<void>;
+}
+export type TableListItem = {
+    name: string;
+    id: string;
+    appliedSchema: InputTableDefinition | null;
+};

package/dist/input-table-db/utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared utilities for the input-table-db SDK.
+ */
+export declare class InputTableError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Validate that a string is a safe identifier (alphanumeric, underscores, hyphens).
+ * Prevents path traversal and injection via solutionId, tableName, docId.
+ */
+export declare function validateIdentifier(value: string, label: string): string;
+/**
+ * Validate a checkpoint timestamp value matches ISO format.
+ */
+export declare function validateCheckpointTimestamp(value: string): string;
+/**
+ * Validate a checkpoint ID value is a safe identifier.
+ */
+export declare function validateCheckpointId(value: string): string;
+/**
+ * Strip null values from a row and coerce PK to string.
+ * Used by both replication and realtime binding.
+ */
+export declare function stripNullsAndCoercePk(row: Record<string, unknown>, primaryKeyField: string): Record<string, unknown>;
+/**
+ * Deferred subscription helper — used by all Lazy* wrappers to avoid boilerplate.
+ * Resolves the async subscription source, connects the callback, and returns
+ * an unsubscribe function that cleans up even if the resolve hasn't completed yet.
+ */
+export declare function deferSubscription<T>(resolve: () => Promise<(callback: (value: T) => void) => () => void>, callback: (value: T) => void, fallback: T): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/core",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "type": "module",
   "main": "dist/index.es.js",
   "module": "dist/index.es.js",
@@ -18,12 +18,17 @@
     "build": "vite build",
     "build:umd": "vite build --config vite.umd.config.ts",
     "dev": "vite build --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.5",
     "typescript": "5.9.2",
     "vite": "5.4.21",
-    "vite-plugin-dts": "4.5.4"
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "4.0.5"
   },
   "author": "Bluecopa",
   "license": "MIT",
@@ -37,6 +42,8 @@
     "axios": "1.13.5",
     "centrifuge": "5.2.2",
     "lodash": "4.18.1",
-    "pusher-js": "^8.3.0"
+    "pusher-js": "^8.3.0",
+    "rxdb": "^16.21.1",
+    "rxjs": "^7.5.4"
   }
 }