@powersync/common 1.53.1 → 1.54.0

package/src/index.ts

@@ -35,7 +35,7 @@ export * from './db/DBAdapter.js';
 export * from './db/schema/Column.js';
 export * from './db/schema/Index.js';
 export * from './db/schema/IndexedColumn.js';
-export { RawTableType, PendingStatementParameter, PendingStatement } from './db/schema/RawTable.js';
+export { PendingStatement, PendingStatementParameter, RawTableType } from './db/schema/RawTable.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';

package/src/types/types.ts

@@ -1,8 +1,14 @@
+/**
+ * @public
+ */
 export interface CompilableQuery<T> {
   execute(): Promise<T[]>;
   compile(): CompiledQuery;
 }
 
+/**
+ * @public
+ */
 export interface CompiledQuery {
   readonly sql: string;
   readonly parameters: ReadonlyArray<unknown>;

package/src/utils/AbortOperation.ts

@@ -2,6 +2,8 @@
  * Calls to Abortcontroller.abort(reason: any) will result in the
  * `reason` being thrown. This is not necessarily an error,
  *  but extends error for better logging purposes.
+ *
+ * @internal
  */
 export class AbortOperation extends Error {
   constructor(protected reason: string) {

package/src/utils/BaseObserver.ts

@@ -1,13 +1,25 @@
+/**
+ * @public
+ */
 export interface Disposable {
   dispose: () => Promise<void> | void;
 }
 
+/**
+ * @public
+ */
 export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
 
+/**
+ * @public
+ */
 export interface BaseObserverInterface<T extends BaseListener> {
   registerListener(listener: Partial<T>): () => void;
 }
 
+/**
+ * @internal
+ */
 export class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
   protected listeners = new Set<Partial<T>>();
 

package/src/utils/ControlledExecutor.ts

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export interface ControlledExecutorOptions {
   /**
    * If throttling is enabled, it ensures only one task runs at a time,
@@ -7,6 +10,9 @@ export interface ControlledExecutorOptions {
   throttleEnabled?: boolean;
 }
 
+/**
+ * @internal
+ */
 export class ControlledExecutor<T> {
   private task: (param: T) => Promise<void> | void;
 

package/src/utils/Logger.ts

@@ -4,6 +4,9 @@ export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-l
 
 const TypedLogger: ILogger = Logger as any;
 
+/**
+ * @public
+ */
 export const LogLevel = {
   TRACE: TypedLogger.TRACE,
   DEBUG: TypedLogger.DEBUG,
@@ -14,6 +17,9 @@ export const LogLevel = {
   OFF: TypedLogger.OFF
 };
 
+/**
+ * @public
+ */
 export interface CreateLoggerOptions {
   logLevel?: ILogLevel;
 }
@@ -25,6 +31,7 @@ export interface CreateLoggerOptions {
  * across all loggers created with `createLogger`. Adjusting settings on this
  * base logger affects all loggers derived from it unless explicitly overridden.
  *
+ * @public
  */
 export function createBaseLogger() {
   return Logger;
@@ -36,6 +43,8 @@ export function createBaseLogger() {
  * Named loggers allow specific modules or areas of your application to have
  * their own logging levels and behaviors. These loggers inherit configuration
  * from the base logger by default but can override settings independently.
+ *
+ * @public
  */
 export function createLogger(name: string, options: CreateLoggerOptions = {}): ILogger {
   const logger = Logger.get(name);

package/src/utils/async.ts

@@ -19,32 +19,59 @@ export function throttleTrailing(func: () => void, wait: number) {
   };
 }
 
-/**
- * Throttle a function to be called at most once every "wait" milliseconds,
- * on the leading and trailing edge.
- *
- * Roughly equivalent to lodash/throttle with {leading: true, trailing: true}
- */
-export function throttleLeadingTrailing(func: () => void, wait: number) {
-  let timeoutId: ReturnType<typeof setTimeout> | null = null;
-  let lastCallTime: number = 0;
+export interface AsyncNotifier {
+  /**
+   * @param signal Also resolve the promise once this signal completes.
+   * @returns A promise that resolves once {@link notify} is called after this promise was last resolved.
+   */
+  waitForNotification(signal: AbortSignal): Promise<void>;
 
-  const invokeFunction = () => {
-    func();
-    lastCallTime = Date.now();
-    timeoutId = null;
-  };
+  /**
+   * Notifies a pending listener, or makes the next {@link waitForNotification} complete immediately if no listener
+   * is currently active.
+   */
+  notify(): void;
+}
 
-  return function () {
-    const now = Date.now();
-    const timeToWait = wait - (now - lastCallTime);
-
-    if (timeToWait <= 0) {
-      // Leading edge: Call the function immediately if enough time has passed
-      invokeFunction();
-    } else if (!timeoutId) {
-      // Set a timeout for the trailing edge if not already set
-      timeoutId = setTimeout(invokeFunction, timeToWait);
+export function asyncNotifier(): AsyncNotifier {
+  let waitingConsumer: (() => void) | null = null;
+  let hasPendingNotification = false;
+
+  return {
+    notify() {
+      if (waitingConsumer != null) {
+        waitingConsumer();
+        waitingConsumer = null;
+      } else {
+        hasPendingNotification = true;
+      }
+    },
+    waitForNotification(signal: AbortSignal) {
+      return new Promise((resolve) => {
+        if (waitingConsumer != null) {
+          throw new Error('Illegal call to waitForNotification, already has a waiter.');
+        }
+
+        if (signal.aborted) {
+          resolve();
+        } else if (hasPendingNotification) {
+          resolve();
+          hasPendingNotification = false;
+        } else {
+          function complete() {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+          }
+
+          function onAbort() {
+            waitingConsumer = null;
+            resolve();
+          }
+
+          waitingConsumer = complete;
+          signal.addEventListener('abort', onAbort);
+        }
+      });
     }
   };
 }

package/src/utils/mutex.ts

@@ -1,5 +1,8 @@
 import { Queue } from './queue.js';
 
+/**
+ * @internal
+ */
 export type UnlockFn = () => void;
 
 /**
@@ -178,10 +181,19 @@ export class Mutex {
 
 /**
  * Creates a signal aborting after the set timeout.
+ *
+ * @internal
  */
 export function timeoutSignal(timeout: number): AbortSignal;
+
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined;
 
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined {
   if (timeout == null) return;
   if ('timeout' in AbortSignal) return AbortSignal.timeout(timeout);

package/src/utils/parseQuery.ts

@@ -1,10 +1,16 @@
 import type { CompilableQuery } from '../types/types.js';
 
+/**
+ * @internal
+ */
 export interface ParsedQuery {
   sqlStatement: string;
   parameters: any[];
 }
 
+/**
+ * @internal
+ */
 export const parseQuery = <T>(query: string | CompilableQuery<T>, parameters: any[]): ParsedQuery => {
   let sqlStatement: string;
 

package/src/utils/stream_transform.ts

@@ -2,9 +2,11 @@
  * An async iterator that can't be cancelled.
  *
  * To keep data flow simple, we always pass an explicit cancellation token when subscribing to async streams. Once the
- * {@link AbortSignal} aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
+ * `AbortSignal` aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
  * that there's no way to distinguish between streams that have completed normally and streams that have been cancelled,
  * but that is acceptable for our uses of this.
+ *
+ * @internal
  */
 export type SimpleAsyncIterator<T> = Pick<AsyncIterator<T>, 'next'>;