@bluecopa/core 0.1.68 → 0.1.69

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

@@ -1,7 +1,7 @@
 import { RxCollection } from 'rxdb';
 import { RxReplicationState } from 'rxdb/plugins/replication';
 import { IWebsocketProvider } from '../config';
-import { Row, WhereOp, CollectionRef, QueryBuilder, InputTableColumn, AggregateSpec, AggregateResult, GroupedAggregateResult } from './types';
+import { Row, WhereOp, CollectionRef, QueryBuilder, InputTableColumn, AggregateSpec, AggregateResult, GroupedAggregateResult, InputTableDefinition } from './types';
 import { DocRefImpl } from './docRef';
 import { WhereClause } from './aggregateUtils';
 export declare class CollectionRefImpl<TRow extends Row = Row> implements CollectionRef<TRow> {
@@ -12,14 +12,27 @@ export declare class CollectionRefImpl<TRow extends Row = Row> implements Collec
     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);
+    private schema?;
+    private getSchemaForTable?;
+    constructor(collection: RxCollection, solutionId: string, tableName: string, primaryKeyField: string, pkColumn: InputTableColumn | undefined, replicationState: RxReplicationState<any, any>, getWebsocketProvider: () => IWebsocketProvider | undefined, schema?: InputTableDefinition, getSchemaForTable?: (tableName: string) => InputTableDefinition | null);
     private makeQueryBuilder;
     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>;
+    expand(columnNames: string[]): QueryBuilder<TRow>;
     doc(id: string): DocRefImpl<TRow>;
     add(data: Partial<TRow>): Promise<string>;
+    /**
+     * Subscribe to live changes on this collection. Auto-manages the underlying
+     * RxDB collection's pin refcount so the collection stays alive for the
+     * lifetime of the subscription.
+     *
+     * Note: `.get()`, `.count()`, and `DocRef.get()` intentionally do NOT pin
+     * the collection. They are one-shot reads where the caller is expected to
+     * tolerate the collection being LRU-evicted between calls. If you need a
+     * long-lived reference, use `.subscribe(...)`.
+     */
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
     count(callback: (count: number) => void): () => void;

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

@@ -0,0 +1,10 @@
+import { InputTableDefinition, InputTableRelationship } from './types';
+export declare function deriveEmbedAlias(columnName: string, allColumnNames: string[]): string;
+export declare function resolveRelationship(columnName: string, schema: InputTableDefinition): InputTableRelationship;
+export type ExpandDirective = {
+    alias: string;
+    referencedTable: string;
+    fkColumn: string;
+};
+export declare function buildExpandSelectParam(expansions: ExpandDirective[]): string;
+export declare function buildExpandDirectives(columnNames: string[], schema: InputTableDefinition): ExpandDirective[];

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

@@ -0,0 +1,16 @@
+import { Observable } from 'rxjs';
+import { ExpandDirective } from './expandUtils';
+import { Row } from './types';
+export type LookupMaps = Record<string, Map<unknown, Row>>;
+export type ReferencedStream = {
+    stream$: Observable<Row[]>;
+    pkField: string;
+};
+export declare function buildLookupMap(rows: Row[], pkField: string): Map<unknown, Row>;
+export declare function joinRowsWithLookups(primaryRows: Row[], directives: ExpandDirective[], lookups: LookupMaps): Row[];
+export type ExpandedSubscriptionConfig = {
+    primary$: Observable<Row[]>;
+    referenced: Record<string, ReferencedStream>;
+    directives: ExpandDirective[];
+};
+export declare function createExpandedSubscription(config: ExpandedSubscriptionConfig, cb: (rows: Row[]) => void): () => void;

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

@@ -1,6 +1,17 @@
 import { RxCollection } from 'rxdb';
-import { Row, WhereOp, QueryBuilder, AggregateSpec, AggregateResult, GroupedAggregateResult } from './types';
+import { IWebsocketProvider } from '../config';
+import { Row, WhereOp, QueryBuilder, AggregateSpec, AggregateResult, GroupedAggregateResult, InputTableDefinition } from './types';
 import { WhereClause } from './aggregateUtils';
+export type ExpandContext = {
+    schema: InputTableDefinition;
+    expandColumns: string[];
+    solutionId: string;
+    tableName: string;
+    workspaceId: string;
+    getHeaders: () => Record<string, string>;
+    getSchemaForTable: (tableName: string) => InputTableDefinition | null;
+    getWebsocketProvider: () => IWebsocketProvider | undefined;
+};
 type OrderClause = {
     field: string;
     direction: 'asc' | 'desc';
@@ -9,17 +20,22 @@ type AggregateExecutor<TRow extends Row> = <TSpec extends AggregateSpec<TRow>>(w
 export declare class QueryBuilderImpl<TRow extends Row = Row> implements QueryBuilder<TRow> {
     private collection;
     private aggregateExecutor?;
+    private expandContext?;
     private wheres;
     private orders;
     private limitCount;
     private skipCount;
-    constructor(collection: RxCollection, initialWhere?: WhereClause, initialOrder?: OrderClause, initialLimit?: number, initialSkip?: number, aggregateExecutor?: AggregateExecutor<TRow>);
+    constructor(collection: RxCollection, initialWhere?: WhereClause, initialOrder?: OrderClause, initialLimit?: number, initialSkip?: number, aggregateExecutor?: AggregateExecutor<TRow>, expandContext?: ExpandContext);
     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>;
+    expand(columnNames: string[]): QueryBuilder<TRow>;
     subscribe(callback: (rows: TRow[]) => void): () => void;
+    private buildPrimaryStream;
+    private subscribeWithExpand;
     get(): Promise<TRow[]>;
+    private getWithExpand;
     aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
     aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec, options: {
         groupBy: [];

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

@@ -1,3 +1,4 @@
+import { RxCollection } from 'rxdb';
 import { RxReplicationState } from 'rxdb/plugins/replication';
 import { IWebsocketProvider } from '../config';
 export type RealtimeBindingHandle = {
@@ -6,11 +7,20 @@ export type RealtimeBindingHandle = {
 /**
  * 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 }
+ * Backend publishes events on channel:
+ *   public-input-table-v2-{workspaceId}-{solutionId}-{tableName}
  *
- * Since the payload contains no row data, we trigger reSync() on any change
- * to re-pull from the server.
+ * INSERT / UPDATE payloads carry no row data, so we fall back to reSync() and
+ * let the replication cursor pull the new state.
+ *
+ * DELETE payloads carry the deleted rows:
+ *   { event_type: 'DELETE', deleted_rows: [{ ...row }], deleted_count: N }
+ * or, when the batch exceeds the backend's size cap:
+ *   { event_type: 'DELETE', truncated: true, deleted_count: N }
+ *
+ * For DELETE we remove matching local docs directly (the pull cursor can't see
+ * deleted rows, so reSync alone would leave stale tombstones in consumers). If
+ * the payload is truncated or malformed we fall back to reSync() — worst case
+ * the deleted rows linger briefly but no data is lost.
  */
-export declare function createRealtimeBinding(provider: IWebsocketProvider, replicationState: RxReplicationState<any, any>, workspaceId: string, solutionId: string, tableName: string): RealtimeBindingHandle;
+export declare function createRealtimeBinding(provider: IWebsocketProvider, replicationState: RxReplicationState<any, any>, collection: RxCollection, primaryKeyField: string, workspaceId: string, solutionId: string, tableName: string): RealtimeBindingHandle;

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

@@ -12,7 +12,7 @@ export type ManagedCollection = {
     workspaceId: string;
     primaryKeyField: string;
     lastAccessed: number;
-    /** Number of active subscriptions — prevents LRU eviction while > 0 */
+    /** Lifecycle pin count — collection lives while > 0; destroyed at 0. */
     refCount: number;
 };
 /**
@@ -23,6 +23,18 @@ export declare function addRef(managed: ManagedCollection): void;
  * Decrement refCount for a managed collection (call when unsubscribing).
  */
 export declare function releaseRef(managed: ManagedCollection): void;
+/**
+ * Pin a collection for the lifetime of a consumer. Creates the collection on first pin,
+ * increments refCount on each subsequent call.
+ */
+export declare function pinCollection(solutionId: string, tableDef: InputTableDefinition, workspaceId: string, websocketProvider?: IWebsocketProvider): Promise<ManagedCollection>;
+/**
+ * Release a pinned collection. Destroys when refCount reaches zero.
+ */
+export declare function unpinCollection(solutionId: string, tableName: string, workspaceId: string): Promise<void>;
+export declare function getCollectionRefCount(solutionId: string, tableName: string, workspaceId: string): number;
+/** Test-only — drop all tracked collections without network calls. */
+export declare function __resetCollectionManagerForTests(): Promise<void>;
 /**
  * Get or create an RxDB collection for a table.
  * Deduplicates concurrent creation requests. Handles LRU eviction with refcount protection.

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

@@ -11,20 +11,36 @@ export declare enum InputTableColumnType {
     TIME = "time",
     JSONB = "jsonb"
 }
+export declare enum InputTableOnDelete {
+    CASCADE = "cascade",
+    SET_NULL = "set_null",
+    RESTRICT = "restrict"
+}
+export type InputTableRelationship = {
+    column: string;
+    references_table: string;
+    references_column: string;
+    on_delete?: InputTableOnDelete;
+};
 export type InputTableColumn = {
     name: string;
     type: InputTableColumnType;
     nullable?: boolean;
     primary_key?: boolean;
     auto_increment?: boolean;
+    unique?: boolean;
     default?: string | number | boolean | null;
     searchable?: boolean;
 };
 export type InputTableDefinition = {
     name: string;
     columns: InputTableColumn[];
+    relationships?: InputTableRelationship[];
 };
-/** A plain row object returned by the SDK. */
+/**
+ * A plain row object returned by the SDK. Rows produced by an expanded query also
+ * carry nested row objects under the embed alias for each expanded FK column.
+ */
 export type Row = Record<string, unknown>;
 /** Where clause operators */
 export type WhereOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in';
@@ -53,6 +69,12 @@ export interface QueryBuilder<TRow extends Row = Row> {
     orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
     limit(count: number): QueryBuilder<TRow>;
     skip(count: number): QueryBuilder<TRow>;
+    /**
+     * Embed referenced rows for each listed FK column. Rows returned by `.get()` or
+     * `.subscribe()` include the referenced row under an alias derived from the column
+     * name (`customer_id` → `customer`; on collision falls back to `<col>_row`).
+     */
+    expand(columnNames: string[]): QueryBuilder<TRow>;
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
     aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
@@ -74,6 +96,8 @@ export interface CollectionRef<TRow extends Row = Row> {
     orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
     limit(count: number): QueryBuilder<TRow>;
     skip(count: number): QueryBuilder<TRow>;
+    /** See {@link QueryBuilder.expand}. */
+    expand(columnNames: string[]): QueryBuilder<TRow>;
     doc(id: string): DocRef<TRow>;
     add(data: Partial<TRow>): Promise<string>;
     subscribe(callback: (rows: TRow[]) => void): () => void;

package/dist/utils/metric/analysisMethods.d.ts

@@ -12,7 +12,7 @@ export type MetricToolPanelType = {
     limitOptions: LimitOptions;
     filterModel: FilterRule | [];
     dateRange?: DateRange;
-    timeBin: TimeBin | "";
+    timeBin: TimeBin | '';
     currency?: string;
     compareTrends?: Array<{
         id: string;
@@ -20,7 +20,7 @@ export type MetricToolPanelType = {
         dateRange: DateRange;
     }>;
     showDimensionMappingValues?: boolean;
-    plotAsTrendsOrder?: "asc" | "desc" | "none";
+    plotAsTrendsOrder?: 'asc' | 'desc' | 'none';
     showBinSortOrderValues?: boolean;
 };
 export declare const getPivotGridData: (props: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/core",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "type": "module",
   "main": "dist/index.es.js",
   "module": "dist/index.es.js",