@powersync/common 1.36.0 → 1.37.0

package/lib/client/triggers/sanitizeSQL.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export declare function sanitizeUUID(uuid: string): string;
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export declare function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string;

package/lib/client/triggers/sanitizeSQL.js

@@ -0,0 +1,68 @@
+function sanitizeString(input) {
+    return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export function sanitizeUUID(uuid) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    const isValid = uuidRegex.test(uuid);
+    if (!isValid) {
+        throw new Error(`${uuid} is not a valid UUID`);
+    }
+    return uuid;
+}
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export function sanitizeSQL(strings, ...values) {
+    let result = '';
+    strings.forEach((str, i) => {
+        result += str;
+        if (i < values.length) {
+            // For SQL, escape single quotes in string values
+            const value = values[i];
+            if (typeof value == 'string') {
+                result += sanitizeString(value);
+            }
+            else if (value == null) {
+                result += 'NULL';
+            }
+            else if (typeof value == 'object') {
+                // Stringify the object and escape single quotes in the result
+                const stringified = JSON.stringify(value);
+                result += sanitizeString(stringified);
+            }
+            else {
+                result += value;
+            }
+        }
+    });
+    return result;
+}

package/lib/index.d.ts

@@ -30,6 +30,8 @@ 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/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
 export * from './client/watched/GetAllQuery.js';
 export * from './client/watched/processors/AbstractQueryProcessor.js';
 export * from './client/watched/processors/comparators.js';

package/lib/index.js

@@ -30,6 +30,8 @@ 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/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
 export * from './client/watched/GetAllQuery.js';
 export * from './client/watched/processors/AbstractQueryProcessor.js';
 export * from './client/watched/processors/comparators.js';

package/lib/utils/async.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A ponyfill for `Symbol.asyncIterator` that is compatible with the
+ * [recommended polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6)
+ * we recommend for React Native.
+ *
+ * As long as we use this symbol (instead of `for await` and `async *`) in this package, we can be compatible with async
+ * iterators without requiring them.
+ */
+export declare const symbolAsyncIterator: typeof Symbol.asyncIterator;
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.

package/lib/utils/async.js

@@ -1,3 +1,12 @@
+/**
+ * A ponyfill for `Symbol.asyncIterator` that is compatible with the
+ * [recommended polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6)
+ * we recommend for React Native.
+ *
+ * As long as we use this symbol (instead of `for await` and `async *`) in this package, we can be compatible with async
+ * iterators without requiring them.
+ */
+export const symbolAsyncIterator = Symbol.asyncIterator ?? Symbol.for('Symbol.asyncIterator');
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.

package/package.json

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