@powersync/common 1.33.2 → 1.35.0

package/lib/db/schema/RawTable.js

@@ -0,0 +1,32 @@
+/**
+ * Instructs PowerSync to sync data into a "raw" table.
+ *
+ * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+ * using client-side table and column constraints.
+ *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
+ * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+ *
+ * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
+ * stability guarantees.
+ */
+export class RawTable {
+    /**
+     * The name of the table.
+     *
+     * This does not have to match the actual table name in the schema - {@link put} and {@link delete} are free to use
+     * another table. Instead, this name is used by the sync client to recognize that operations on this table (as it
+     * appears in the source / backend database) are to be handled specially.
+     */
+    name;
+    put;
+    delete;
+    constructor(name, type) {
+        this.name = name;
+        this.put = type.put;
+        this.delete = type.delete;
+    }
+}

package/lib/db/schema/Schema.d.ts

@@ -1,3 +1,4 @@
+import { RawTable, RawTableType } from './RawTable.js';
 import { RowType, Table } from './Table.js';
 type SchemaType = Record<string, Table<any>>;
 export type SchemaTableType<S extends SchemaType> = {
@@ -10,7 +11,19 @@ export declare class Schema<S extends SchemaType = SchemaType> {
     readonly types: SchemaTableType<S>;
     readonly props: S;
     readonly tables: Table[];
+    readonly rawTables: RawTable[];
     constructor(tables: Table[] | S);
+    /**
+     * Adds raw tables to this schema. Raw tables are identified by their name, but entirely managed by the application
+     * developer instead of automatically by PowerSync.
+     * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+     * using client-side table and column constraints.
+     * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+     *
+     * @param tables An object of (table name, raw table definition) entries.
+     * @experimental Note that the raw tables API is still experimental and may change in the future.
+     */
+    withRawTables(tables: Record<string, RawTableType>): void;
     validate(): void;
     toJSON(): {
         tables: {
@@ -35,6 +48,7 @@ export declare class Schema<S extends SchemaType = SchemaType> {
                 }[];
             }[];
         }[];
+        raw_tables: RawTable[];
     };
     private convertToClassicTables;
 }

package/lib/db/schema/Schema.js

@@ -1,3 +1,4 @@
+import { RawTable } from './RawTable.js';
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
  */
@@ -8,6 +9,7 @@ export class Schema {
     types;
     props;
     tables;
+    rawTables;
     constructor(tables) {
         if (Array.isArray(tables)) {
             /*
@@ -26,6 +28,22 @@ export class Schema {
             this.props = tables;
             this.tables = this.convertToClassicTables(this.props);
         }
+        this.rawTables = [];
+    }
+    /**
+     * Adds raw tables to this schema. Raw tables are identified by their name, but entirely managed by the application
+     * developer instead of automatically by PowerSync.
+     * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+     * using client-side table and column constraints.
+     * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+     *
+     * @param tables An object of (table name, raw table definition) entries.
+     * @experimental Note that the raw tables API is still experimental and may change in the future.
+     */
+    withRawTables(tables) {
+        for (const [name, rawTableDefinition] of Object.entries(tables)) {
+            this.rawTables.push(new RawTable(name, rawTableDefinition));
+        }
     }
     validate() {
         for (const table of this.tables) {
@@ -35,7 +53,8 @@ export class Schema {
     toJSON() {
         return {
             // This is required because "name" field is not present in TableV2
-            tables: this.tables.map((t) => t.toJSON())
+            tables: this.tables.map((t) => t.toJSON()),
+            raw_tables: this.rawTables
         };
     }
     convertToClassicTables(props) {

package/lib/index.d.ts

@@ -29,8 +29,16 @@ export * from './db/schema/IndexedColumn.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';
+export * from './client/Query.js';
+export * from './client/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
 export * from './utils/DataStream.js';
 export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';

package/lib/index.js

@@ -29,8 +29,16 @@ export * from './db/schema/IndexedColumn.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';
+export * from './client/Query.js';
+export * from './client/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
 export * from './utils/DataStream.js';
 export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';

package/lib/utils/BaseObserver.d.ts

@@ -1,15 +1,14 @@
 export interface Disposable {
-    dispose: () => Promise<void>;
+    dispose: () => Promise<void> | void;
 }
+export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
 export interface BaseObserverInterface<T extends BaseListener> {
     registerListener(listener: Partial<T>): () => void;
 }
-export type BaseListener = {
-    [key: string]: ((...event: any) => any) | undefined;
-};
 export declare class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
     protected listeners: Set<Partial<T>>;
     constructor();
+    dispose(): void;
     /**
      * Register a listener for updates to the PowerSync client.
      */

package/lib/utils/BaseObserver.js

@@ -1,6 +1,9 @@
 export class BaseObserver {
     listeners = new Set();
     constructor() { }
+    dispose() {
+        this.listeners.clear();
+    }
     /**
      * Register a listener for updates to the PowerSync client.
      */

package/lib/utils/MetaBaseObserver.d.ts

@@ -0,0 +1,29 @@
+import { BaseListener, BaseObserver, BaseObserverInterface } from './BaseObserver.js';
+/**
+ * Represents the counts of listeners for each event type in a BaseListener.
+ */
+export type ListenerCounts<Listener extends BaseListener> = Partial<Record<keyof Listener, number>> & {
+    total: number;
+};
+/**
+ * Meta listener which reports the counts of listeners for each event type.
+ */
+export interface MetaListener<ParentListener extends BaseListener> extends BaseListener {
+    listenersChanged?: (counts: ListenerCounts<ParentListener>) => void;
+}
+export interface ListenerMetaManager<Listener extends BaseListener> extends BaseObserverInterface<MetaListener<Listener>> {
+    counts: ListenerCounts<Listener>;
+}
+export interface MetaBaseObserverInterface<Listener extends BaseListener> extends BaseObserverInterface<Listener> {
+    listenerMeta: ListenerMetaManager<Listener>;
+}
+/**
+ * A BaseObserver that tracks the counts of listeners for each event type.
+ */
+export declare class MetaBaseObserver<Listener extends BaseListener> extends BaseObserver<Listener> implements MetaBaseObserverInterface<Listener> {
+    protected get listenerCounts(): ListenerCounts<Listener>;
+    get listenerMeta(): ListenerMetaManager<Listener>;
+    protected metaListener: BaseObserver<MetaListener<Listener>>;
+    constructor();
+    registerListener(listener: Partial<Listener>): () => void;
+}

package/lib/utils/MetaBaseObserver.js

@@ -0,0 +1,50 @@
+import { BaseObserver } from './BaseObserver.js';
+/**
+ * A BaseObserver that tracks the counts of listeners for each event type.
+ */
+export class MetaBaseObserver extends BaseObserver {
+    get listenerCounts() {
+        const counts = {};
+        let total = 0;
+        for (const listener of this.listeners) {
+            for (const key in listener) {
+                if (listener[key]) {
+                    counts[key] = (counts[key] ?? 0) + 1;
+                    total++;
+                }
+            }
+        }
+        return {
+            ...counts,
+            total
+        };
+    }
+    get listenerMeta() {
+        return {
+            counts: this.listenerCounts,
+            // Allows registering a meta listener that will be notified of changes in listener counts
+            registerListener: (listener) => {
+                return this.metaListener.registerListener(listener);
+            }
+        };
+    }
+    metaListener;
+    constructor() {
+        super();
+        this.metaListener = new BaseObserver();
+    }
+    registerListener(listener) {
+        const dispose = super.registerListener(listener);
+        const updatedCount = this.listenerCounts;
+        this.metaListener.iterateListeners((l) => {
+            l.listenersChanged?.(updatedCount);
+        });
+        return () => {
+            dispose();
+            const updatedCount = this.listenerCounts;
+            this.metaListener.iterateListeners((l) => {
+                l.listenersChanged?.(updatedCount);
+            });
+        };
+    }
+}

package/lib/utils/async.d.ts

@@ -12,4 +12,3 @@ export declare function throttleTrailing(func: () => void, wait: number): () =>
  * Roughly equivalent to lodash/throttle with {leading: true, trailing: true}
  */
 export declare function throttleLeadingTrailing(func: () => void, wait: number): () => void;
-export declare function onAbortPromise(signal: AbortSignal): Promise<void>;

package/lib/utils/async.js

@@ -43,13 +43,3 @@ export function throttleLeadingTrailing(func, wait) {
         }
     };
 }
-export function onAbortPromise(signal) {
-    return new Promise((resolve) => {
-        if (signal.aborted) {
-            resolve();
-        }
-        else {
-            signal.onabort = () => resolve();
-        }
-    });
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.33.2",
+  "version": "1.35.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"