Enumerations
Classes
Interfaces
AbstractQueryProcessorOptions<Data, Settings>
Internal
Extended by
Type Parameters
Properties
AbstractStreamingSyncImplementationOptions
Internal
Extends
Extended by
Properties
AdditionalConnectionOptions
Internal
Extended by
Properties
| Property | Type | Description |
|---|
crudUploadThrottleMs? | number | Backend Connector CRUD operations are throttled to occur at most every crudUploadThrottleMs milliseconds. |
retryDelayMs? | number | Delay for retrying sync streaming operations from the PowerSync backend after an error occurs. |
ArrayQueryDefinition<RowType>
Options for building a query with AbstractPowerSyncDatabase#query.
This query will be executed with AbstractPowerSyncDatabase#getAll.
Type Parameters
| Type Parameter | Default type |
|---|
RowType | unknown |
Properties
| Property | Type | Description |
|---|
mapper? | (row: Record<string, unknown>) => RowType | Maps the raw SQLite row to a custom typed object. Example mapper: (row) => ({ ...row, created_at: new Date(row.created_at as string), }) |
parameters? | readonly Readonly<QueryParam>[] | - |
sql | string | - |
AsyncDatabaseConnection<Config>
Internal
An async Database connection which provides basic async SQL methods.
This is usually a proxied through a web worker.
Type Parameters
Methods
close()
Returns
Promise<void>
execute()
execute(sql, params?): Promise<ProxiedQueryResult>
Parameters
| Parameter | Type |
|---|
sql | string |
params? | any[] |
Returns
Promise<ProxiedQueryResult>
executeBatch()
executeBatch(sql, params?): Promise<ProxiedQueryResult>
Parameters
| Parameter | Type |
|---|
sql | string |
params? | any[] |
Returns
Promise<ProxiedQueryResult>
executeRaw()
executeRaw(sql, params?): Promise<any[][]>
Parameters
| Parameter | Type |
|---|
sql | string |
params? | any[] |
Returns
Promise<any[][]>
getConfig()
getConfig(): Promise<Config>
Returns
Promise<Config>
init()
Returns
Promise<void>
isAutoCommit()
isAutoCommit(): Promise<boolean>
Checks if the database connection is in autocommit mode.
Returns
Promise<boolean>
true if in autocommit mode, false if in a transaction
markHold()
markHold(): Promise<string>
Marks the connection as in-use by a certain actor.
Returns
Promise<string>
A hold ID which can be used to release the hold.
registerOnTableChange()
registerOnTableChange(callback): Promise<() => void>
Parameters
Returns
Promise<() => void>
releaseHold()
releaseHold(holdId): Promise<void>
Releases a hold on the connection.
Parameters
| Parameter | Type | Description |
|---|
holdId | string | The hold ID to release. |
Returns
Promise<void>
BaseConnectionOptions
Internal
Extended by
Properties
| Property | Type | Description |
|---|
appMetadata? | Record<string, string> | A set of metadata to be included in service logs. |
clientImplementation? | SyncClientImplementation | Whether to use a JavaScript implementation to handle received sync lines from the sync service, or whether this work should be offloaded to the PowerSync core extension. This defaults to the JavaScript implementation (SyncClientImplementation.JAVASCRIPT) since the (SyncClientImplementation.RUST) implementation is experimental at the moment. |
connectionMethod? | SyncStreamConnectionMethod | The connection method to use when streaming updates from the PowerSync backend instance. Defaults to a HTTP streaming connection. |
fetchStrategy? | FetchStrategy | The fetch strategy to use when streaming updates from the PowerSync backend instance. |
includeDefaultStreams? | boolean | Whether to include streams that have auto_subscribe: true in their definition. This defaults to true. |
params? | Record<string, JSONValue> | These parameters are passed to the sync rules, and will be available under theuser_parameters object. |
serializedSchema? | any | The serialized schema - mainly used to forward information about raw tables to the sync client. |
BaseObserverInterface<T>
Extended by
Type Parameters
Methods
registerListener()
registerListener(listener): () => void
Parameters
| Parameter | Type |
|---|
listener | Partial<T> |
Returns
Function
Returns
void
BasePowerSyncDatabaseOptions
Internal
Extends
Extended by
Properties
| Property | Type | Description | Inherited from |
|---|
crudUploadThrottleMs? | number | Backend Connector CRUD operations are throttled to occur at most every crudUploadThrottleMs milliseconds. | AdditionalConnectionOptions.crudUploadThrottleMs |
logger? | ILogger | - | - |
retryDelay? | number | Deprecated Use retryDelayMs instead as this will be removed in future releases. | - |
retryDelayMs? | number | Delay for retrying sync streaming operations from the PowerSync backend after an error occurs. | AdditionalConnectionOptions.retryDelayMs |
schema | Schema | Schema used for the local database. | - |
BaseTriggerDiffRecord<TOperationId>
Experimental
Diffs created by TriggerManager#createDiffTrigger are stored in a temporary table.
This is the base record structure for all diff records.
Extended by
Type Parameters
| Type Parameter | Default type | Description |
|---|
TOperationId extends string | number | number | The type for operation_id. Defaults to number as returned by default SQLite database queries. Use string for full 64-bit precision when using { castOperationIdAsText: true } option. |
Properties
| Property | Type | Description |
|---|
id | string | Experimental The modified row's id column value. |
operation | DiffTriggerOperation | Experimental The operation performed which created this record. |
operation_id | TOperationId | Experimental Auto-incrementing primary key for the operation. Defaults to number as returned by database queries (wa-sqlite returns lower 32 bits). Can be string for full 64-bit precision when using { castOperationIdAsText: true } option. |
timestamp | string | Experimental Time the change operation was recorded. This is in ISO 8601 format, e.g. 2023-10-01T12:00:00.000Z. |
BatchedUpdateNotification
Properties
BucketChecksum
Properties
| Property | Type | Description |
|---|
bucket | string | - |
checksum | number | 32-bit unsigned hash. |
count? | number | Count of operations - informational only. |
priority? | number | - |
subscriptions? | any | The JavaScript client does not use this field, which is why it's defined to be any. We rely on the structure of this interface to pass custom BucketChecksums to the Rust client in unit tests, which so all fields need to be present. |
BucketDescription
Properties
| Property | Type |
|---|
name | string |
priority | number |
BucketRequest
Properties
| Property | Type | Description |
|---|
after | string | Base-10 number. Sync all data from this bucket with op_id > after. |
name | string | - |
BucketState
Properties
| Property | Type |
|---|
bucket | string |
op_id | string |
BucketStorageAdapter
Extends
Properties
Methods
control()
control(op, payload): Promise<string>
Invokes the powersync_control function for the sync client.
Parameters
Returns
Promise<string>
getBucketOperationProgress()
getBucketOperationProgress(): Promise<BucketOperationProgress>
Returns
Promise<BucketOperationProgress>
getBucketStates()
getBucketStates(): Promise<BucketState[]>
Returns
Promise<BucketState[]>
getClientId()
getClientId(): Promise<string>
Get an unique client id.
Returns
Promise<string>
getCrudBatch()
getCrudBatch(limit?): Promise<null | CrudBatch>
Parameters
| Parameter | Type |
|---|
limit? | number |
Returns
Promise<null | CrudBatch>
getMaxOpId()
Returns
string
hasCompletedSync()
hasCompletedSync(): Promise<boolean>
Returns
Promise<boolean>
hasCrud()
hasCrud(): Promise<boolean>
Returns
Promise<boolean>
hasMigratedSubkeys()
hasMigratedSubkeys(): Promise<boolean>
Returns
Promise<boolean>
init()
Returns
Promise<void>
migrateToFixedSubkeys()
migrateToFixedSubkeys(): Promise<void>
Returns
Promise<void>
nextCrudItem()
nextCrudItem(): Promise<undefined | CrudEntry>
Returns
Promise<undefined | CrudEntry>
registerListener()
registerListener(listener): () => void
Parameters
Returns
Function
Returns
void
Inherited from
BaseObserverInterface.registerListener
removeBuckets()
removeBuckets(buckets): Promise<void>
Parameters
| Parameter | Type |
|---|
buckets | string[] |
Returns
Promise<void>
saveSyncData()
saveSyncData(batch, fixedKeyFormat?): Promise<void>
Parameters
Returns
Promise<void>
setTargetCheckpoint()
setTargetCheckpoint(checkpoint): Promise<void>
Parameters
Returns
Promise<void>
startSession()
Returns
void
syncLocalDatabase()
syncLocalDatabase(checkpoint, priority?): Promise<{
checkpointValid: boolean;
failures: any[];
ready: boolean;
}>
Parameters
Returns
Promise<{
checkpointValid: boolean;
failures: any[];
ready: boolean;
}>
updateLocalTarget()
updateLocalTarget(cb): Promise<boolean>
Parameters
| Parameter | Type |
|---|
cb | () => Promise<string> |
Returns
Promise<boolean>
BucketStorageListener
Extends
Indexable
[key: string]: undefined | (...event) => any
Properties
| Property | Type |
|---|
crudUpdate | () => void |
Checkpoint
Properties
| Property | Type |
|---|
buckets | BucketChecksum[] |
last_op_id | string |
streams? | any[] |
write_checkpoint? | string |
ChecksumCache
Properties
| Property | Type |
|---|
checksums | Map<string, { checksum: BucketChecksum; last_op_id: string; }> |
lastOpId | string |
ColumnOptions
Properties
CompilableQuery<T>
Type Parameters
Methods
compile()
Returns
CompiledQuery
execute()
Returns
Promise<T[]>
CompilableQueryWatchHandler<T>
Type Parameters
Properties
| Property | Type |
|---|
onError? | (error: Error) => void |
onResult | (results: T[]) => void |
CompiledQuery
Properties
| Property | Modifier | Type |
|---|
parameters | readonly | readonly unknown[] |
sql | readonly | string |
ConnectionManagerListener
Internal
Extends
Indexable
[key: string]: undefined | (...event) => any
Properties
ConnectionManagerOptions
Internal
Properties
| Property | Type |
|---|
logger | ILogger |
Methods
createSyncImplementation()
createSyncImplementation(connector, options): Promise<ConnectionManagerSyncImplementationResult>
Parameters
Returns
Promise<ConnectionManagerSyncImplementationResult>
ConnectionManagerSyncImplementationResult
Internal
Properties
| Property | Type | Description |
|---|
onDispose | () => void | Promise<void> | Additional cleanup function which is called after the sync stream implementation is disposed. |
sync | StreamingSyncImplementation | - |
ContinueCheckpointRequest
For sync2.json
Properties
| Property | Type | Description |
|---|
buckets | BucketRequest[] | Existing bucket states. Only these buckets are synchronized. |
checkpoint_token | string | - |
limit? | number | - |
ControlledExecutorOptions
Properties
| Property | Type | Description |
|---|
throttleEnabled? | boolean | If throttling is enabled, it ensures only one task runs at a time, and only one additional task can be scheduled to run after the current task completes. The pending task will be overwritten by the latest task. Enabled by default. |
CreateDiffTriggerOptions
Experimental
Options for TriggerManager#createDiffTrigger.
Extends
BaseCreateDiffTriggerOptions
Properties
| Property | Type | Description | Inherited from |
|---|
columns? | string[] | Experimental Columns to track and report changes for. Defaults to all columns in the source table. Use an empty array to track only the ID and operation. | BaseCreateDiffTriggerOptions.columns |
destination | string | Experimental Destination table to send changes to. This table is created internally as a SQLite temporary table. This table will be dropped once the trigger is removed. | - |
hooks? | TriggerCreationHooks | Experimental Hooks which allow execution during the trigger creation process. | BaseCreateDiffTriggerOptions.hooks |
source | string | Experimental PowerSync source table/view to trigger and track changes from. This should be present in the PowerSync database's schema. | BaseCreateDiffTriggerOptions.source |
when | Partial<Record<DiffTriggerOperation, string>> | Experimental Condition to filter when the triggers should fire. This corresponds to a SQLite WHEN clause in the trigger body. This is useful for only triggering on specific conditions. For example, you can use it to only trigger on certain values in the NEW row. Note that for PowerSync the row data is stored in a JSON column named data. The row id is available in the id column. NB! The WHEN clauses here are added directly to the SQLite trigger creation SQL. Any user input strings here should be sanitized externally. The when string template function performs some basic sanitization, extra external sanitization is recommended. Example { * 'INSERT': sanitizeSQLjson_extract(NEW.data, '$.list_id') = ${sanitizeUUID(list.id)}, * 'INSERT': TRUE, * 'UPDATE': sanitizeSQLNEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active', * 'DELETE': sanitizeSQLjson_extract(OLD.data, '$.list_id') = 'abcd' * } | BaseCreateDiffTriggerOptions.when |
CreateLoggerOptions
Properties
| Property | Type |
|---|
logLevel? | ILogLevel |
CreateSyncImplementationOptions
Internal
The subset of AbstractStreamingSyncImplementationOptions managed by the connection manager.
Extends
Properties
CrudRequest
For crud.json
Properties
CrudResponse
Properties
| Property | Type | Description |
|---|
checkpoint? | string | A sync response with a checkpoint >= this checkpoint would contain all the changes in this request. Any earlier checkpoint may or may not contain these changes. May be empty when the request contains no ops. |
DataStreamListener<Data>
Extends
Type Parameters
| Type Parameter | Default type |
|---|
Data extends any | any |
Indexable
[key: string]: undefined | (...event) => any
Properties
| Property | Type |
|---|
closed | () => void |
data | (data: Data) => Promise<void> |
error | (error: Error) => void |
highWater | () => Promise<void> |
lowWater | () => Promise<void> |
DBAdapter
Extends
Properties
| Property | Type | Description |
|---|
close | () => void | Promise<void> | - |
execute | (query: string, params?: any[]) => Promise<QueryResult> | - |
executeBatch | (query: string, params?: any[][]) => Promise<QueryResult> | - |
executeRaw | (query: string, params?: any[]) => Promise<any[][]> | - |
name | string | - |
readLock | <T>(fn: (tx) => Promise<T>, options?: DBLockOptions) => Promise<T> | - |
readTransaction | <T>(fn: (tx) => Promise<T>, options?: DBLockOptions) => Promise<T> | - |
refreshSchema | () => Promise<void> | This method refreshes the schema information across all connections. This is for advanced use cases, and should generally not be needed. |
writeLock | <T>(fn: (tx) => Promise<T>, options?: DBLockOptions) => Promise<T> | - |
writeTransaction | <T>(fn: (tx) => Promise<T>, options?: DBLockOptions) => Promise<T> | - |
Methods
get()
get<T>(sql, parameters?): Promise<T>
Execute a read-only query and return the first result, error if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T>
Inherited from
DBGetUtils.get
getAll()
getAll<T>(sql, parameters?): Promise<T[]>
Execute a read-only query and return results.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T[]>
Inherited from
DBGetUtils.getAll
getOptional()
getOptional<T>(sql, parameters?): Promise<null | T>
Execute a read-only query and return the first result, or null if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<null | T>
Inherited from
DBGetUtils.getOptional
registerListener()
registerListener(listener): () => void
Parameters
Returns
Function
Returns
void
Inherited from
BaseObserverInterface.registerListener
DBAdapterListener
Extends
Indexable
[key: string]: undefined | (...event) => any
Properties
| Property | Type | Description |
|---|
tablesUpdated | (updateNotification: | BatchedUpdateNotification | UpdateNotification) => void | Listener for table updates. Allows for single table updates in order to maintain API compatibility without the need for a major version bump The DB adapter can also batch update notifications if supported. |
DBGetUtils
Extended by
Methods
get()
get<T>(sql, parameters?): Promise<T>
Execute a read-only query and return the first result, error if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T>
getAll()
getAll<T>(sql, parameters?): Promise<T[]>
Execute a read-only query and return results.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T[]>
getOptional()
getOptional<T>(sql, parameters?): Promise<null | T>
Execute a read-only query and return the first result, or null if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<null | T>
DBLockOptions
Properties
| Property | Type |
|---|
timeoutMs? | number |
DifferentialQueryProcessorOptions<RowType>
Internal
Extends
Type Parameters
Properties
DifferentialWatchedQueryComparator<RowType>
Row comparator for differentially watched queries which keys and compares items in the result set.
Type Parameters
Properties
| Property | Type | Description |
|---|
compareBy | (item: RowType) => string | Generates a token for comparing items with matching keys. |
keyBy | (item: RowType) => string | Generates a unique key for the item. |
DifferentialWatchedQueryListener<RowType>
Extends
Type Parameters
Indexable
[key: string]: undefined | (...event) => any
Properties
DifferentialWatchedQueryOptions<RowType>
Options for building a differential watched query with the Query builder.
Extends
Extended by
Type Parameters
Properties
| Property | Type | Default value | Description | Inherited from |
|---|
placeholderData? | RowType[] | undefined | Initial result data which is presented while the initial loading is executing. | - |
reportFetching? | boolean | undefined | If true (default) the watched query will update its state to report on the fetching state of the query. Setting to false reduces the number of state changes if the fetch status is not relevant to the consumer. | WatchedQueryOptions.reportFetching |
rowComparator? | DifferentialWatchedQueryComparator<RowType> | DEFAULT_ROW_COMPARATOR | Row comparator used to identify and compare rows in the result set. If not provided, the default comparator will be used which keys items by their id property if available, otherwise it uses JSON stringification of the entire item for keying and comparison. | - |
throttleMs? | number | undefined | The minimum interval between queries. | WatchedQueryOptions.throttleMs |
triggerOnTables? | string[] | undefined | By default, watched queries requery the database on any change to any dependent table of the query. Supplying an override here can be used to limit the tables which trigger querying the database. | WatchedQueryOptions.triggerOnTables |
DifferentialWatchedQuerySettings<RowType>
Settings for differential incremental watched queries using.
Extends
Type Parameters
Properties
| Property | Type | Default value | Description | Inherited from |
|---|
placeholderData? | RowType[] | undefined | Initial result data which is presented while the initial loading is executing. | DifferentialWatchedQueryOptions.placeholderData |
query | WatchCompatibleQuery<RowType[]> | undefined | The query here must return an array of items that can be differentiated. | - |
reportFetching? | boolean | undefined | If true (default) the watched query will update its state to report on the fetching state of the query. Setting to false reduces the number of state changes if the fetch status is not relevant to the consumer. | DifferentialWatchedQueryOptions.reportFetching |
rowComparator? | DifferentialWatchedQueryComparator<RowType> | DEFAULT_ROW_COMPARATOR | Row comparator used to identify and compare rows in the result set. If not provided, the default comparator will be used which keys items by their id property if available, otherwise it uses JSON stringification of the entire item for keying and comparison. | DifferentialWatchedQueryOptions.rowComparator |
throttleMs? | number | undefined | The minimum interval between queries. | DifferentialWatchedQueryOptions.throttleMs |
triggerOnTables? | string[] | undefined | By default, watched queries requery the database on any change to any dependent table of the query. Supplying an override here can be used to limit the tables which trigger querying the database. | DifferentialWatchedQueryOptions.triggerOnTables |
DisconnectAndClearOptions
Properties
| Property | Type | Description |
|---|
clearLocal? | boolean | When set to false, data in local-only tables is preserved. |
Disposable
Extended by
Properties
| Property | Type |
|---|
dispose | () => void | Promise<void> |
IndexColumnOptions
Properties
| Property | Type |
|---|
ascending? | boolean |
name | string |
IndexOptions
Properties
InternalConnectionOptions
Internal
Extends
Properties
InternalSubscriptionAdapter
Methods
firstStatusMatching()
firstStatusMatching(predicate, abort?): Promise<void>
Parameters
| Parameter | Type |
|---|
predicate | (status) => any |
abort? | AbortSignal |
Returns
Promise<void>
resolveOfflineSyncStatus()
resolveOfflineSyncStatus(): Promise<void>
Returns
Promise<void>
rustSubscriptionsCommand()
rustSubscriptionsCommand(payload): Promise<void>
Parameters
Returns
Promise<void>
LinkQueryOptions<Data, Settings>
Internal
Type Parameters
Properties
| Property | Type |
|---|
abortSignal | AbortSignal |
settings | Settings |
LockContext
Extends
Extended by
Properties
| Property | Type | Description |
|---|
execute | (query: string, params?: any[]) => Promise<QueryResult> | Execute a single write statement. |
executeRaw | (query: string, params?: any[]) => Promise<any[][]> | Execute a single write statement and return raw results. Unlike execute, which returns an object with structured key-value pairs, executeRaw returns a nested array of raw values, where each row is represented as an array of column values without field names. Example result: [ [ '1', 'list 1', '33', 'Post content', '1' ] ] Where as execute's rows._array would have been: [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ] |
Methods
get()
get<T>(sql, parameters?): Promise<T>
Execute a read-only query and return the first result, error if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T>
Inherited from
DBGetUtils.get
getAll()
getAll<T>(sql, parameters?): Promise<T[]>
Execute a read-only query and return results.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T[]>
Inherited from
DBGetUtils.getAll
getOptional()
getOptional<T>(sql, parameters?): Promise<null | T>
Execute a read-only query and return the first result, or null if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<null | T>
Inherited from
DBGetUtils.getOptional
LockOptions<T>
Abstract Lock to be implemented by various JS environments
Type Parameters
Properties
| Property | Type |
|---|
callback | () => Promise<T> |
signal? | AbortSignal |
type | LockType |
OnChangeQueryProcessorOptions<Data>
Internal
Extends
Type Parameters
Properties
OplogEntryJSON
Properties
| Property | Type |
|---|
checksum | number |
data? | string |
object_id? | string |
object_type? | string |
op | string |
op_id | string |
subkey? | string |
ParsedQuery
Properties
| Property | Type |
|---|
parameters | any[] |
sqlStatement | string |
PowerSyncBackendConnector
Properties
| Property | Type | Description |
|---|
fetchCredentials | () => Promise<null | PowerSyncCredentials> | Allows the PowerSync client to retrieve an authentication token from your backend which is used to authenticate against the PowerSync service. This should always fetch a fresh set of credentials - don't use cached values. Return null if the user is not signed in. Throw an error if credentials cannot be fetched due to a network error or other temporary error. This token is kept for the duration of a sync connection. |
uploadData | (database: AbstractPowerSyncDatabase) => Promise<void> | Upload local changes to the app backend. Use AbstractPowerSyncDatabase.getCrudBatch to get a batch of changes to upload. Any thrown errors will result in a retry after the configured wait period (default: 5 seconds). |
PowerSyncCloseOptions
Properties
| Property | Type | Description |
|---|
disconnect? | boolean | Disconnect the sync stream client if connected. This is usually true, but can be false for Web when using multiple tabs and a shared sync provider. |
PowerSyncCredentials
Properties
| Property | Type |
|---|
endpoint | string |
expiresAt? | Date |
token | string |
PowerSyncDatabaseOptions
Internal
Extends
Properties
PowerSyncDatabaseOptionsWithDBAdapter
Internal
Extends
Properties
PowerSyncDatabaseOptionsWithOpenFactory
Internal
Extends
Properties
PowerSyncDatabaseOptionsWithSettings
Internal
Extends
Properties
PowerSyncDBListener
Extends
Indexable
[key: string]: undefined | (...event) => any
Properties
PowerSyncOpenFactoryOptions
Extends
Extended by
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|
crudUploadThrottleMs? | number | Backend Connector CRUD operations are throttled to occur at most every crudUploadThrottleMs milliseconds. | - | Partial.crudUploadThrottleMs |
database? | | SQLOpenOptions | DBAdapter | SQLOpenFactory | Source for a SQLite database connection. This can be either: - A DBAdapter if providing an instantiated SQLite connection - A SQLOpenFactory which will be used to open a SQLite connection - SQLOpenOptions for opening a SQLite connection with a default SQLOpenFactory | - | Partial.database |
dbFilename | string | Filename for the database. | - | SQLOpenOptions.dbFilename |
dbLocation? | string | Directory where the database file is located. When set, the directory must exist when the database is opened, it will not be created automatically. | - | SQLOpenOptions.dbLocation |
debugMode? | boolean | Enable debugMode to log queries to the performance timeline. Defaults to false. To enable in development builds, use: debugMode: process.env.NODE_ENV !== 'production' | - | SQLOpenOptions.debugMode |
logger? | ILogger | - | - | Partial.logger |
retryDelay? | number | Deprecated Use retryDelayMs instead as this will be removed in future releases. | - | Partial.retryDelay |
retryDelayMs? | number | Delay for retrying sync streaming operations from the PowerSync backend after an error occurs. | - | Partial.retryDelayMs |
schema | Schema | Schema used for the local database. | Partial.schema | - |
ProgressWithOperations
Information about a progressing download made by the PowerSync SDK.
To obtain these values, use SyncProgress, available through
SyncStatus#downloadProgress.
Properties
| Property | Type | Description |
|---|
downloadedFraction | number | Relative progress, as downloadedOperations of totalOperations. This will be a number between 0.0 and 1.0 (inclusive). When this number reaches 1.0, all changes have been received from the sync service. Actually applying these changes happens before the downloadProgress field is cleared from SyncStatus, so progress can stay at 1.0 for a short while before completing. |
downloadedOperations | number | The amount of operations that have already been downloaded. |
totalOperations | number | The total amount of operations to download for the current sync iteration to complete. |
Query<RowType>
Type Parameters
Methods
differentialWatch()
differentialWatch(options?): DifferentialWatchedQuery<RowType>
Creates a WatchedQuery which watches and emits results of the linked query.
This query method watches for changes in the underlying SQLite tables and runs the query on each table change.
The difference between the current and previous result set is computed.
The watched query will not emit changes if the result set is identical to the previous result set.
If the result set is different, the watched query will emit the new result set and emit a detailed diff of the changes via the onData and onDiff listeners.
The deep differentiation allows maintaining result set object references between result emissions.
The DifferentialWatchedQuery#state data array will contain the previous row references for unchanged rows.
Parameters
Returns
DifferentialWatchedQuery<RowType>
Example
const watchedLists = powerSync.query({sql: 'SELECT * FROM lists'})
.differentialWatch();
const disposeListener = watchedLists.registerListener({
onData: (lists) => {
console.log('The latest result set for the query is', lists);
},
onDiff: (diff) => {
console.log('The lists result set has changed since the last emission', diff.added, diff.removed, diff.updated, diff.all)
}
})
watch()
watch(options?): StandardWatchedQuery<readonly Readonly<RowType>[]>
Creates a WatchedQuery which watches and emits results of the linked query.
By default the returned watched query will emit changes whenever a change to the underlying SQLite tables is made.
These changes might not be relevant to the query, but the query will emit a new result set.
A StandardWatchedQueryOptions#comparator can be provided to limit the data emissions. The watched query will still
query the underlying DB on underlying table changes, but the result will only be emitted if the comparator detects a change in the results.
The comparator in this method is optimized and returns early as soon as it detects a change. Each data emission will correlate to a change in the result set,
but note that the result set will not maintain internal object references to the previous result set. If internal object references are needed,
consider using Query#differentialWatch instead.
Parameters
Returns
StandardWatchedQuery<readonly Readonly<RowType>[]>
RequiredAdditionalConnectionOptions
Internal
Extends
Extended by
Properties
| Property | Type | Description | Inherited from |
|---|
crudUploadThrottleMs | number | Backend Connector CRUD operations are throttled to occur at most every crudUploadThrottleMs milliseconds. | Required.crudUploadThrottleMs |
retryDelayMs | number | Delay for retrying sync streaming operations from the PowerSync backend after an error occurs. | Required.retryDelayMs |
subscriptions | SubscribedStream[] | - | - |
ResolvedWASQLiteOpenFactoryOptions
Extends
Extended by
Properties
ResolvedWebSQLOpenOptions
Extends
Extended by
Properties
| Property | Type | Description | Inherited from |
|---|
cacheSizeKb | number | - | - |
dbFilename | string | Filename for the database. | SQLOpenOptions.dbFilename |
dbLocation? | string | Directory where the database file is located. When set, the directory must exist when the database is opened, it will not be created automatically. | SQLOpenOptions.dbLocation |
debugMode? | boolean | Enable debugMode to log queries to the performance timeline. Defaults to false. To enable in development builds, use: debugMode: process.env.NODE_ENV !== 'production' | SQLOpenOptions.debugMode |
encryptionKey? | string | Encryption key for the database. If set, the database will be encrypted using ChaCha20. | - |
flags | Required | - | - |
temporaryStorage | TemporaryStorageOption | Where to store SQLite temporary files. Defaults to 'MEMORY'. Setting this to FILESYSTEM can cause issues with larger queries or datasets. | - |
SharedWebStreamingSyncImplementationOptions
Internal
Extends
Properties
SQLOnChangeOptions
Extended by
Properties
| Property | Type | Description |
|---|
rawTableNames? | boolean | Deprecated All tables specified in tables will be watched, including PowerSync tables with prefixes. Allows for watching any SQL table by not removing PowerSync table name prefixes |
signal? | AbortSignal | - |
tables? | string[] | - |
throttleMs? | number | The minimum interval between queries. |
triggerImmediate? | boolean | Emits an empty result set immediately |
SQLOpenFactory
Methods
openDB()
Opens a connection adapter to a SQLite DB
Returns
DBAdapter
SQLOpenOptions
Extended by
Properties
| Property | Type | Description |
|---|
dbFilename | string | Filename for the database. |
dbLocation? | string | Directory where the database file is located. When set, the directory must exist when the database is opened, it will not be created automatically. |
debugMode? | boolean | Enable debugMode to log queries to the performance timeline. Defaults to false. To enable in development builds, use: debugMode: process.env.NODE_ENV !== 'production' |
SQLWatchOptions
Extends
Properties
StandardWatchedQueryOptions<RowType>
Options for Query#watch.
Extends
Type Parameters
Properties
| Property | Type | Description | Inherited from |
|---|
comparator? | WatchedQueryComparator<RowType[]> | The underlying watched query implementation (re)evaluates the query on any SQLite table change. Providing this optional comparator can be used to filter duplicate result set emissions when the result set is unchanged. The comparator compares the previous and current result set. For an efficient comparator see ArrayComparator. Example comparator: new ArrayComparator({ compareBy: (item) => JSON.stringify(item) }) | - |
placeholderData? | RowType[] | The initial data state reported while the query is loading for the first time. Default [] | - |
reportFetching? | boolean | If true (default) the watched query will update its state to report on the fetching state of the query. Setting to false reduces the number of state changes if the fetch status is not relevant to the consumer. | WatchedQueryOptions.reportFetching |
throttleMs? | number | The minimum interval between queries. | WatchedQueryOptions.throttleMs |
triggerOnTables? | string[] | By default, watched queries requery the database on any change to any dependent table of the query. Supplying an override here can be used to limit the tables which trigger querying the database. | WatchedQueryOptions.triggerOnTables |
StreamingSyncCheckpoint
Properties
StreamingSyncCheckpointComplete
Properties
| Property | Type |
|---|
checkpoint_complete | { last_op_id: string; } |
checkpoint_complete.last_op_id | string |
StreamingSyncCheckpointDiff
Properties
| Property | Type |
|---|
checkpoint_diff | { last_op_id: string; removed_buckets: string[]; updated_buckets: BucketChecksum[]; write_checkpoint: string; } |
checkpoint_diff.last_op_id | string |
checkpoint_diff.removed_buckets | string[] |
checkpoint_diff.updated_buckets | BucketChecksum[] |
checkpoint_diff.write_checkpoint? | string |
StreamingSyncCheckpointPartiallyComplete
Properties
| Property | Type |
|---|
partial_checkpoint_complete | { last_op_id: string; priority: number; } |
partial_checkpoint_complete.last_op_id | string |
partial_checkpoint_complete.priority | number |
StreamingSyncDataJSON
Properties
StreamingSyncImplementation
Extends
Properties
| Property | Type | Inherited from |
|---|
dispose | () => void | Promise<void> | Disposable.dispose |
getWriteCheckpoint | () => Promise<string> | - |
hasCompletedSync | () => Promise<boolean> | - |
isConnected | boolean | - |
lastSyncedAt? | Date | - |
syncStatus | SyncStatus | - |
triggerCrudUpload | () => void | - |
Methods
connect()
connect(options?): Promise<void>
Connects to the sync service
Parameters
Returns
Promise<void>
disconnect()
disconnect(): Promise<void>
Disconnects from the sync services.
Returns
Promise<void>
Throws
if not connected or if abort is not controlled internally
registerListener()
registerListener(listener): () => void
Parameters
Returns
Function
Returns
void
Inherited from
BaseObserverInterface.registerListener
updateSubscriptions()
updateSubscriptions(subscriptions): void
Parameters
Returns
void
waitForReady()
waitForReady(): Promise<void>
Returns
Promise<void>
waitForStatus()
waitForStatus(status): Promise<void>
Parameters
Returns
Promise<void>
waitUntilStatusMatches()
waitUntilStatusMatches(predicate): Promise<void>
Parameters
| Parameter | Type |
|---|
predicate | (status) => boolean |
Returns
Promise<void>
StreamingSyncImplementationListener
Extends
Extended by
Indexable
[key: string]: undefined | (...event) => any
Properties
| Property | Type | Description |
|---|
statusChanged? | (status: SyncStatus) => void | Triggers whenever the status' members have changed in value |
statusUpdated? | (statusUpdate: SyncStatusOptions) => void | Triggered whenever a status update has been attempted to be made or refreshed. |
StreamingSyncKeepalive
Properties
| Property | Type | Description |
|---|
token_expires_in | number | If specified, token expires in this many seconds. |
StreamingSyncRequest
Properties
| Property | Type | Description |
|---|
app_metadata? | Record<string, string> | Application metadata to be included in service logs. |
buckets? | BucketRequest[] | Existing bucket states. |
client_id? | string | - |
include_checksum | boolean | Whether or not to compute a checksum for each checkpoint |
only? | string[] | If specified, limit the response to only include these buckets. |
parameters? | Record<string, JSONValue> | Client parameters to be passed to the sync rules. |
raw_data | boolean | Changes the response to stringified data in each OplogEntry |
SyncLocalDatabaseResult
Properties
| Property | Type |
|---|
checkpointFailures? | string[] |
checkpointValid | boolean |
ready | boolean |
SyncNewCheckpointRequest
Properties
| Property | Type | Description |
|---|
buckets? | BucketRequest[] | Existing bucket states. Used if include_data is specified. |
limit? | number | - |
request_checkpoint | { include_checksum: boolean; include_data: boolean; } | - |
request_checkpoint.include_checksum | boolean | Whether or not to compute a checksum. |
request_checkpoint.include_data | boolean | Whether or not to include an initial data request. |
SyncPriorityStatus
Properties
| Property | Type |
|---|
hasSynced? | boolean |
lastSyncedAt? | Date |
priority | number |
SyncResponse
Properties
| Property | Type | Description |
|---|
checkpoint? | Checkpoint | - |
checkpoint_token? | string | - |
data? | SyncDataBucketJSON[] | Data for the buckets returned. May not have an an entry for each bucket in the request. |
has_more | boolean | True if the response limit has been reached, and another request must be made. |
SyncStream
A handle to a SyncStreamDescription that allows subscribing to the stream.
To obtain an instance of SyncStream, call AbstractPowerSyncDatabase.syncStream.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
name | string | The name of the stream as it appears in the stream definition for the PowerSync service. | SyncStreamDescription.name |
parameters | null | Record<string, any> | The parameters used to subscribe to the stream, if any. The same stream can be subscribed to multiple times with different parameters. | SyncStreamDescription.parameters |
Methods
subscribe()
subscribe(options?): Promise<SyncStreamSubscription>
Adds a subscription to this stream, requesting it to be included when connecting to the sync service.
You should keep a reference to the returned SyncStreamSubscription object along as you need data for that
stream. As soon as SyncStreamSubscription.unsubscribe is called for all subscriptions on this stream
(including subscriptions created on other tabs), the SyncStreamSubscribeOptions.ttl starts ticking and will
eventually evict the stream (unless subscribe is called again).
Parameters
Returns
Promise<SyncStreamSubscription>
unsubscribeAll()
unsubscribeAll(): Promise<void>
Clears all subscriptions attached to this stream and resets the TTL for the stream.
This is a potentially dangerous operations, as it interferes with other stream subscriptions.
Returns
Promise<void>
SyncStreamDescription
A description of a sync stream, consisting of its name and the parameters used when subscribing.
Extended by
Properties
| Property | Type | Description |
|---|
name | string | The name of the stream as it appears in the stream definition for the PowerSync service. |
parameters | null | Record<string, any> | The parameters used to subscribe to the stream, if any. The same stream can be subscribed to multiple times with different parameters. |
SyncStreamStatus
Information about a sync stream subscription.
Properties
SyncStreamSubscribeOptions
Properties
| Property | Type | Description |
|---|
priority? | 0 | 1 | 2 | 3 | A priority to assign to this subscription. This overrides the default priority that may have been set on streams. For details on priorities, see priotized sync. |
ttl? | number | A "time to live" for this stream subscription, in seconds. The TTL control when a stream gets evicted after not having an active SyncStreamSubscription object attached to it. |
SyncStreamSubscription
A description of a sync stream, consisting of its name and the parameters used when subscribing.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
name | string | The name of the stream as it appears in the stream definition for the PowerSync service. | SyncStreamDescription.name |
parameters | null | Record<string, any> | The parameters used to subscribe to the stream, if any. The same stream can be subscribed to multiple times with different parameters. | SyncStreamDescription.parameters |
Methods
unsubscribe()
Removes this stream subscription.
Returns
void
waitForFirstSync()
waitForFirstSync(abort?): Promise<void>
A promise that resolves once data from in this sync stream has been synced and applied.
Parameters
| Parameter | Type |
|---|
abort? | AbortSignal |
Returns
Promise<void>
SyncSubscriptionDescription
Information about a subscribed sync stream.
This includes the SyncStreamDescription, along with information about the current sync status.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
active | boolean | - | - |
expiresAt | null | Date | For sync streams that have a time-to-live, the current time at which the stream would expire if not subscribed to again. | - |
hasExplicitSubscription | boolean | Whether this stream has been subscribed to explicitly. It's possible for both isDefault and hasExplicitSubscription to be true at the same time - this happens when a default stream was subscribed explicitly. | - |
hasSynced | boolean | Whether this stream subscription has been synced at least once. | - |
isDefault | boolean | Whether this stream subscription is included by default, regardless of whether the stream has explicitly been subscribed to or not. It's possible for both isDefault and hasExplicitSubscription to be true at the same time - this happens when a default stream was subscribed explicitly. | - |
lastSyncedAt | null | Date | If hasSynced is true, the last time data from this stream has been synced. | - |
name | string | The name of the stream as it appears in the stream definition for the PowerSync service. | SyncStreamDescription.name |
parameters | null | Record<string, any> | The parameters used to subscribe to the stream, if any. The same stream can be subscribed to multiple times with different parameters. | SyncStreamDescription.parameters |
TableOptions
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
columns | Column[] | - | - |
ignoreEmptyUpdates? | boolean | - | SharedTableOptions.ignoreEmptyUpdates |
indexes? | Index[] | - | - |
insertOnly? | boolean | - | SharedTableOptions.insertOnly |
localOnly? | boolean | - | SharedTableOptions.localOnly |
name | string | The synced table name, matching sync rules | - |
trackMetadata? | boolean | - | SharedTableOptions.trackMetadata |
trackPrevious? | boolean | TrackPreviousOptions | - | SharedTableOptions.trackPrevious |
viewName? | string | - | SharedTableOptions.viewName |
TableUpdateOperation
Extended by
Properties
TableV2Options
Extends
Properties
| Property | Type | Inherited from |
|---|
ignoreEmptyUpdates? | boolean | SharedTableOptions.ignoreEmptyUpdates |
indexes? | IndexShorthand | - |
insertOnly? | boolean | SharedTableOptions.insertOnly |
localOnly? | boolean | SharedTableOptions.localOnly |
trackMetadata? | boolean | SharedTableOptions.trackMetadata |
trackPrevious? | boolean | TrackPreviousOptions | SharedTableOptions.trackPrevious |
viewName? | string | SharedTableOptions.viewName |
TrackDiffOptions
Experimental
Options for tracking changes to a table with TriggerManager#trackTableDiff.
Extends
BaseCreateDiffTriggerOptions
Properties
| Property | Type | Description | Inherited from |
|---|
columns? | string[] | Experimental Columns to track and report changes for. Defaults to all columns in the source table. Use an empty array to track only the ID and operation. | BaseCreateDiffTriggerOptions.columns |
hooks? | TriggerCreationHooks | Experimental Hooks which allow execution during the trigger creation process. | BaseCreateDiffTriggerOptions.hooks |
onChange | (context: TriggerDiffHandlerContext) => Promise<void> | Experimental Handler for processing diff operations. Automatically invoked once diff items are present. Diff items are automatically cleared after the handler is invoked. | - |
source | string | Experimental PowerSync source table/view to trigger and track changes from. This should be present in the PowerSync database's schema. | BaseCreateDiffTriggerOptions.source |
throttleMs? | number | Experimental The minimum interval, in milliseconds, between onChange invocations. Default DEFAULT_WATCH_THROTTLE_MS | - |
when | Partial<Record<DiffTriggerOperation, string>> | Experimental Condition to filter when the triggers should fire. This corresponds to a SQLite WHEN clause in the trigger body. This is useful for only triggering on specific conditions. For example, you can use it to only trigger on certain values in the NEW row. Note that for PowerSync the row data is stored in a JSON column named data. The row id is available in the id column. NB! The WHEN clauses here are added directly to the SQLite trigger creation SQL. Any user input strings here should be sanitized externally. The when string template function performs some basic sanitization, extra external sanitization is recommended. Example { * 'INSERT': sanitizeSQLjson_extract(NEW.data, '$.list_id') = ${sanitizeUUID(list.id)}, * 'INSERT': TRUE, * 'UPDATE': sanitizeSQLNEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active', * 'DELETE': sanitizeSQLjson_extract(OLD.data, '$.list_id') = 'abcd' * } | BaseCreateDiffTriggerOptions.when |
TrackPreviousOptions
Whether to include previous column values when PowerSync tracks local changes.
Including old values may be helpful for some backend connector implementations, which is
why it can be enabled on per-table or per-columm basis.
Properties
| Property | Type | Description |
|---|
columns? | string[] | When defined, a list of column names for which old values should be tracked. |
onlyWhenChanged? | boolean | When enabled, only include values that have actually been changed by an update. |
Transaction
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
commit | () => Promise<QueryResult> | Commit multiple changes to the local DB using the Transaction context. | - |
execute | (query: string, params?: any[]) => Promise<QueryResult> | Execute a single write statement. | LockContext.execute |
executeRaw | (query: string, params?: any[]) => Promise<any[][]> | Execute a single write statement and return raw results. Unlike execute, which returns an object with structured key-value pairs, executeRaw returns a nested array of raw values, where each row is represented as an array of column values without field names. Example result: [ [ '1', 'list 1', '33', 'Post content', '1' ] ] Where as execute's rows._array would have been: [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ] | LockContext.executeRaw |
rollback | () => Promise<QueryResult> | Roll back multiple attempted changes using the Transaction context. | - |
Methods
get()
get<T>(sql, parameters?): Promise<T>
Execute a read-only query and return the first result, error if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T>
Inherited from
LockContext.get
getAll()
getAll<T>(sql, parameters?): Promise<T[]>
Execute a read-only query and return results.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T[]>
Inherited from
LockContext.getAll
getOptional()
getOptional<T>(sql, parameters?): Promise<null | T>
Execute a read-only query and return the first result, or null if the ResultSet is empty.
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<null | T>
Inherited from
LockContext.getOptional
TriggerCreationHooks
Experimental
Hooks used in the creation of a table diff trigger.
Properties
| Property | Type | Description |
|---|
beforeCreate? | (context: LockContext) => Promise<void> | Experimental Executed inside a write lock before the trigger is created. |
TriggerDiffDeleteRecord<TOperationId>
Experimental
Represents a diff record for a SQLite DELETE operation.
This record contains the new value represented as a JSON string.
Extends
Type Parameters
| Type Parameter | Default type |
|---|
TOperationId extends string | number | number |
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|
id | string | Experimental The modified row's id column value. | - | BaseTriggerDiffRecord.id |
operation | DELETE | Experimental The operation performed which created this record. | BaseTriggerDiffRecord.operation | - |
operation_id | TOperationId | Experimental Auto-incrementing primary key for the operation. Defaults to number as returned by database queries (wa-sqlite returns lower 32 bits). Can be string for full 64-bit precision when using { castOperationIdAsText: true } option. | - | BaseTriggerDiffRecord.operation_id |
timestamp | string | Experimental Time the change operation was recorded. This is in ISO 8601 format, e.g. 2023-10-01T12:00:00.000Z. | - | BaseTriggerDiffRecord.timestamp |
value | string | Experimental The value of the row, before the DELETE operation, in JSON string format. | - | - |
TriggerDiffHandlerContext
Experimental
Context for the onChange handler provided to TriggerManager#trackTableDiff.
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
destinationTable | string | Experimental The name of the temporary destination table created by the trigger. | - |
execute | (query: string, params?: any[]) => Promise<QueryResult> | Experimental Execute a single write statement. | LockContext.execute |
executeRaw | (query: string, params?: any[]) => Promise<any[][]> | Experimental Execute a single write statement and return raw results. Unlike execute, which returns an object with structured key-value pairs, executeRaw returns a nested array of raw values, where each row is represented as an array of column values without field names. Example result: [ [ '1', 'list 1', '33', 'Post content', '1' ] ] Where as execute's rows._array would have been: [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ] | LockContext.executeRaw |
withDiff | <T>(query: string, params?: readonly Readonly<any>[], options?: WithDiffOptions) => Promise<T[]> | Experimental Allows querying the database with access to the table containing DIFF records. The diff table is accessible via the DIFF accessor. The DIFF table is of the form described in TriggerManager#createDiffTrigger CREATE TEMP DIFF ( operation_id INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT, operation TEXT, timestamp TEXT, value TEXT, previous_value TEXT ); Note that the value and previous_value columns store the row state in JSON string format. To access the row state in an extracted form see TriggerDiffHandlerContext#withExtractedDiff. Examples --- This fetches the current state of todo rows which have a diff operation present. --- The state of the row at the time of the operation is accessible in the DIFF records. SELECT todos.* FROM DIFF JOIN todos ON DIFF.id = todos.id WHERE json_extract(DIFF.value, '$.status') = 'active' // With operation_id cast as TEXT for full precision const diffs = await context.withDiff<TriggerDiffRecord<string>>( 'SELECT * FROM DIFF', undefined, { castOperationIdAsText: true } ); // diffs[0].operation_id is now typed as string | - |
withExtractedDiff | <T>(query: string, params?: readonly Readonly<any>[]) => Promise<T[]> | Experimental Allows querying the database with access to the table containing diff records. The diff table is accessible via the DIFF accessor. This is similar to withDiff but extracts the row columns from the tracked JSON value. The diff operation data is aliased as __ columns to avoid column conflicts. For DiffTriggerOperation#DELETE operations the previous_value columns are extracted for convenience. CREATE TEMP TABLE DIFF ( id TEXT, replicated_column_1 COLUMN_TYPE, replicated_column_2 COLUMN_TYPE, __operation TEXT, __timestamp TEXT, __previous_value TEXT ); Example SELECT todos.* FROM DIFF JOIN todos ON DIFF.id = todos.id --- The todo column names are extracted from json and are available as DIFF.name WHERE DIFF.name = 'example' | - |
Methods
get()
get<T>(sql, parameters?): Promise<T>
Experimental
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T>
Inherited from
LockContext.get
getAll()
getAll<T>(sql, parameters?): Promise<T[]>
Experimental
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<T[]>
Inherited from
LockContext.getAll
getOptional()
getOptional<T>(sql, parameters?): Promise<null | T>
Experimental
Type Parameters
Parameters
| Parameter | Type |
|---|
sql | string |
parameters? | any[] |
Returns
Promise<null | T>
Inherited from
LockContext.getOptional
TriggerDiffInsertRecord<TOperationId>
Experimental
Represents a diff record for a SQLite INSERT operation.
This record contains the new value represented as a JSON string.
Extends
Type Parameters
| Type Parameter | Default type |
|---|
TOperationId extends string | number | number |
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|
id | string | Experimental The modified row's id column value. | - | BaseTriggerDiffRecord.id |
operation | INSERT | Experimental The operation performed which created this record. | BaseTriggerDiffRecord.operation | - |
operation_id | TOperationId | Experimental Auto-incrementing primary key for the operation. Defaults to number as returned by database queries (wa-sqlite returns lower 32 bits). Can be string for full 64-bit precision when using { castOperationIdAsText: true } option. | - | BaseTriggerDiffRecord.operation_id |
timestamp | string | Experimental Time the change operation was recorded. This is in ISO 8601 format, e.g. 2023-10-01T12:00:00.000Z. | - | BaseTriggerDiffRecord.timestamp |
value | string | Experimental The value of the row, at the time of INSERT, in JSON string format. | - | - |
TriggerDiffUpdateRecord<TOperationId>
Experimental
Represents a diff record for a SQLite UPDATE operation.
This record contains the new value and optionally the previous value.
Values are stored as JSON strings.
Extends
Type Parameters
| Type Parameter | Default type |
|---|
TOperationId extends string | number | number |
Properties
| Property | Type | Description | Overrides | Inherited from |
|---|
id | string | Experimental The modified row's id column value. | - | BaseTriggerDiffRecord.id |
operation | UPDATE | Experimental The operation performed which created this record. | BaseTriggerDiffRecord.operation | - |
operation_id | TOperationId | Experimental Auto-incrementing primary key for the operation. Defaults to number as returned by database queries (wa-sqlite returns lower 32 bits). Can be string for full 64-bit precision when using { castOperationIdAsText: true } option. | - | BaseTriggerDiffRecord.operation_id |
previous_value | string | Experimental The previous value of the row in JSON string format. | - | - |
timestamp | string | Experimental Time the change operation was recorded. This is in ISO 8601 format, e.g. 2023-10-01T12:00:00.000Z. | - | BaseTriggerDiffRecord.timestamp |
value | string | Experimental The updated state of the row in JSON string format. | - | - |
TriggerManager
Experimental
Methods
createDiffTrigger()
createDiffTrigger(options): Promise<TriggerRemoveCallback>
Experimental
Parameters
Returns
Promise<TriggerRemoveCallback>
A callback to remove the trigger and drop the destination table.
Example
const dispose = await database.triggers.createDiffTrigger({
source: 'lists',
destination: 'ps_temp_lists_diff',
columns: ['name'],
when: {
[DiffTriggerOperation.INSERT]: 'TRUE',
[DiffTriggerOperation.UPDATE]: 'TRUE',
[DiffTriggerOperation.DELETE]: 'TRUE'
}
});
trackTableDiff()
trackTableDiff(options): Promise<TriggerRemoveCallback>
Experimental
Parameters
Returns
Promise<TriggerRemoveCallback>
A callback to cleanup the trigger and stop tracking changes.
NB: The triggers created by this method might be invalidated by AbstractPowerSyncDatabase#updateSchema calls.
These triggers should manually be dropped and recreated when updating the schema.
Example
const dispose = database.triggers.trackTableDiff({
source: 'todos',
columns: ['list_id'],
when: {
[DiffTriggerOperation.INSERT]: sanitizeSQL`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(someIdVariable)}`
},
onChange: async (context) => {
const newTodos = await context.withDiff<Database['todos']>(`
SELECT
todos.*
FROM
DIFF
JOIN todos ON DIFF.id = todos.id
`);
},
hooks: {
beforeCreate: async (lockContext) => {
const currentTodos = await lockContext.getAll<Database['todos']>(
`
SELECT
*
FROM
todos
WHERE
list_id = ?
`,
['123']
);
}
}
});
UpdateNotification
Notification of an update to one or more tables, for the purpose of realtime change notifications.
Extends
Properties
WASQLiteDBAdapterOptions
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
cacheSizeKb? | number | - | - |
crudUploadThrottleMs? | number | Backend Connector CRUD operations are throttled to occur at most every crudUploadThrottleMs milliseconds. | Omit.crudUploadThrottleMs |
database? | | SQLOpenOptions | DBAdapter | SQLOpenFactory | Source for a SQLite database connection. This can be either: - A DBAdapter if providing an instantiated SQLite connection - A SQLOpenFactory which will be used to open a SQLite connection - SQLOpenOptions for opening a SQLite connection with a default SQLOpenFactory | Omit.database |
dbFilename | string | Filename for the database. | Omit.dbFilename |
dbLocation? | string | Directory where the database file is located. When set, the directory must exist when the database is opened, it will not be created automatically. | Omit.dbLocation |
debugMode? | boolean | Enable debugMode to log queries to the performance timeline. Defaults to false. To enable in development builds, use: debugMode: process.env.NODE_ENV !== 'production' | Omit.debugMode |
encryptionKey? | string | Encryption key for the database. If set, the database will be encrypted using multiple-ciphers. | - |
flags? | WebSQLFlags | - | - |
logger? | ILogger | - | Omit.logger |
retryDelay? | number | Deprecated Use retryDelayMs instead as this will be removed in future releases. | Omit.retryDelay |
retryDelayMs? | number | Delay for retrying sync streaming operations from the PowerSync backend after an error occurs. | Omit.retryDelayMs |
temporaryStorage? | TemporaryStorageOption | - | - |
vfs? | WASQLiteVFS | - | - |
worker? | string | URL | (options) => Worker | SharedWorker | - | - |
workerPort? | MessagePort | Use an existing port to an initialized worker. A worker will be initialized if none is provided | - |
WASQLiteOpenFactoryOptions
Options for opening a Web SQL connection
Extends
Properties
WatchCompatibleQuery<ResultType>
Similar to CompatibleQuery, except the execute method
does not enforce an Array result type.
Type Parameters
Methods
compile()
Returns
CompiledQuery
execute()
execute(options): Promise<ResultType>
Parameters
Returns
Promise<ResultType>
WatchedQuery<Data, Settings, Listener>
Extends
MetaBaseObserverInterface<Listener>
Type Parameters
Properties
| Property | Modifier | Type | Description | Inherited from |
|---|
closed | readonly | boolean | - | - |
listenerMeta | public | ListenerMetaManager<Listener> | - | MetaBaseObserverInterface.listenerMeta |
state | readonly | WatchedQueryState<Data> | Current state of the watched query. | - |
Methods
close()
Close the watched query and end all subscriptions.
Returns
Promise<void>
registerListener()
registerListener(listener): () => void
Subscribe to watched query events.
Parameters
| Parameter | Type |
|---|
listener | Listener |
Returns
Function
A function to unsubscribe from the events.
Returns
void
Overrides
MetaBaseObserverInterface.registerListener
updateSettings()
updateSettings(options): Promise<void>
Updates the underlying query options.
This will trigger a re-evaluation of the query and update the state.
Parameters
| Parameter | Type |
|---|
options | Settings |
Returns
Promise<void>
WatchedQueryComparator<Data>
A basic comparator for incrementally watched queries. This performs a single comparison which
determines if the result set has changed. The WatchedQuery will only emit the new result
if a change has been detected.
Type Parameters
Properties
| Property | Type |
|---|
checkEquality | (current: Data, previous: Data) => boolean |
WatchedQueryDifferential<RowType>
Represents the result of a watched query that has been diffed.
DifferentialWatchedQueryState#diff is of the WatchedQueryDifferential form.
Type Parameters
Properties
| Property | Modifier | Type | Description |
|---|
added | readonly | readonly Readonly<RowType>[] | - |
all | readonly | readonly Readonly<RowType>[] | The entire current result set. Array item object references are preserved between updates if the item is unchanged. e.g. In the query SELECT name, make FROM assets ORDER BY make ASC; If a previous result set contains an item (A) {name: 'pc', make: 'Cool PC'} and an update has been made which adds another item (B) to the result set (the item A is unchanged) - then the updated result set will be contain the same object reference, to item A, as the previous result set. This is regardless of the item A's position in the updated result set. |
removed | readonly | readonly Readonly<RowType>[] | - |
unchanged | readonly | readonly Readonly<RowType>[] | - |
updated | readonly | readonly WatchedQueryRowDifferential<Readonly<RowType>>[] | - |
WatchedQueryListener<Data>
Extends
Extended by
Type Parameters
Indexable
[key: string]: undefined | (...event) => any
Properties
| Property | Type |
|---|
closed? | () => void | Promise<void> |
onData? | (data: Data) => void | Promise<void> |
onError? | (error: Error) => void | Promise<void> |
onStateChange? | (state: WatchedQueryState<Data>) => void | Promise<void> |
settingsWillUpdate? | () => void |
WatchedQueryOptions
Extended by
Properties
| Property | Type | Description |
|---|
reportFetching? | boolean | If true (default) the watched query will update its state to report on the fetching state of the query. Setting to false reduces the number of state changes if the fetch status is not relevant to the consumer. |
throttleMs? | number | The minimum interval between queries. |
triggerOnTables? | string[] | By default, watched queries requery the database on any change to any dependent table of the query. Supplying an override here can be used to limit the tables which trigger querying the database. |
WatchedQueryRowDifferential<RowType>
Represents an updated row in a differential watched query.
It contains both the current and previous state of the row.
Type Parameters
Properties
| Property | Modifier | Type |
|---|
current | readonly | RowType |
previous | readonly | RowType |
WatchedQuerySettings<DataType>
Settings for WatchedQuery instances created via Query#watch.
Extends
Type Parameters
Properties
| Property | Type | Description | Inherited from |
|---|
query | WatchCompatibleQuery<DataType> | - | - |
reportFetching? | boolean | If true (default) the watched query will update its state to report on the fetching state of the query. Setting to false reduces the number of state changes if the fetch status is not relevant to the consumer. | WatchedQueryOptions.reportFetching |
throttleMs? | number | The minimum interval between queries. | WatchedQueryOptions.throttleMs |
triggerOnTables? | string[] | By default, watched queries requery the database on any change to any dependent table of the query. Supplying an override here can be used to limit the tables which trigger querying the database. | WatchedQueryOptions.triggerOnTables |
WatchedQueryState<Data>
State for WatchedQuery instances.
Type Parameters
Properties
| Property | Modifier | Type | Description |
|---|
data | readonly | Data | The last data returned by the query. |
error | readonly | null | Error | The last error that occurred while executing the query. |
isFetching | readonly | boolean | Indicates whether the query is currently fetching data, is true during the initial load and any time when the query is re-evaluating (useful for large queries). |
isLoading | readonly | boolean | Indicates the initial loading state (hard loading). Loading becomes false once the first set of results from the watched query is available or an error occurs. |
lastUpdated | readonly | null | Date | The last time the query was updated. |
WatchExecuteOptions
Options provided to the execute method of a WatchCompatibleQuery.
Properties
WatchHandler
Properties
| Property | Type |
|---|
onError? | (error: Error) => void |
onResult | (results: QueryResult) => void |
WatchOnChangeEvent
Properties
| Property | Type |
|---|
changedTables | string[] |
WatchOnChangeHandler
Properties
| Property | Type |
|---|
onChange | (event: WatchOnChangeEvent) => void | Promise<void> |
onError? | (error: Error) => void |
WebEncryptionOptions
Properties
| Property | Type | Description |
|---|
encryptionKey? | string | Encryption key for the database. If set, the database will be encrypted using Multiple Ciphers. |
WebPowerSyncFlags
Common settings used when creating SQL connections on web.
Extends
Extended by
Properties
| Property | Type | Description | Inherited from |
|---|
broadcastLogs? | boolean | Broadcast logs from shared workers, such as the shared sync worker, to individual tabs. This defaults to true. | WebSQLFlags.broadcastLogs |
disableSSRWarning? | boolean | SQLite operations are currently not supported in SSR mode. A warning will be logged if attempting to use SQLite in SSR. Setting this to true will disabled the warning above. | WebSQLFlags.disableSSRWarning |
enableMultiTabs? | boolean | Enables multi tab support | WebSQLFlags.enableMultiTabs |
externallyUnload? | boolean | Externally unload open PowerSync database instances when the window closes. Setting this to true requires calling close on all open PowerSyncDatabase instances before the window unloads | - |
ssrMode? | boolean | Open in SSR placeholder mode. DB operations and Sync operations will be a No-op | WebSQLFlags.ssrMode |
useWebWorker? | boolean | The SQLite connection is often executed through a web worker in order to offload computation. This can be used to manually disable the use of web workers in environments where web workers might be unstable. | WebSQLFlags.useWebWorker |
WebPowerSyncOpenFactoryOptions
Extends
Properties
WebPowerSyncOpenFlags
WebPowerSyncFlags
Maintaining export for consistency with API from previous versions
Extends
Properties
| Property | Type | Description | Inherited from |
|---|
broadcastLogs? | boolean | Broadcast logs from shared workers, such as the shared sync worker, to individual tabs. This defaults to true. | WebPowerSyncFlags.broadcastLogs |
disableSSRWarning? | boolean | SQLite operations are currently not supported in SSR mode. A warning will be logged if attempting to use SQLite in SSR. Setting this to true will disabled the warning above. | WebPowerSyncFlags.disableSSRWarning |
enableMultiTabs? | boolean | Enables multi tab support | WebPowerSyncFlags.enableMultiTabs |
externallyUnload? | boolean | Externally unload open PowerSync database instances when the window closes. Setting this to true requires calling close on all open PowerSyncDatabase instances before the window unloads | WebPowerSyncFlags.externallyUnload |
ssrMode? | boolean | Open in SSR placeholder mode. DB operations and Sync operations will be a No-op | WebPowerSyncFlags.ssrMode |
useWebWorker? | boolean | The SQLite connection is often executed through a web worker in order to offload computation. This can be used to manually disable the use of web workers in environments where web workers might be unstable. | WebPowerSyncFlags.useWebWorker |
WebSQLFlags
Common settings used when creating SQL connections on web.
Extended by
Properties
| Property | Type | Description |
|---|
broadcastLogs? | boolean | Broadcast logs from shared workers, such as the shared sync worker, to individual tabs. This defaults to true. |
disableSSRWarning? | boolean | SQLite operations are currently not supported in SSR mode. A warning will be logged if attempting to use SQLite in SSR. Setting this to true will disabled the warning above. |
enableMultiTabs? | boolean | Enables multi tab support |
ssrMode? | boolean | Open in SSR placeholder mode. DB operations and Sync operations will be a No-op |
useWebWorker? | boolean | The SQLite connection is often executed through a web worker in order to offload computation. This can be used to manually disable the use of web workers in environments where web workers might be unstable. |
WebSQLOpenFactoryOptions
Options for opening a Web SQL connection
Extends
Extended by
Properties
| Property | Type | Description | Inherited from |
|---|
cacheSizeKb? | number | Maximum SQLite cache size. Defaults to 50MB. For details, see: https://www.sqlite.org/pragma.html#pragma_cache_size | - |
dbFilename | string | Filename for the database. | SQLOpenOptions.dbFilename |
dbLocation? | string | Directory where the database file is located. When set, the directory must exist when the database is opened, it will not be created automatically. | SQLOpenOptions.dbLocation |
debugMode? | boolean | Enable debugMode to log queries to the performance timeline. Defaults to false. To enable in development builds, use: debugMode: process.env.NODE_ENV !== 'production' | SQLOpenOptions.debugMode |
encryptionKey? | string | Encryption key for the database. If set, the database will be encrypted using ChaCha20. | - |
flags? | WebSQLFlags | - | - |
logger? | ILogger | - | - |
temporaryStorage? | TemporaryStorageOption | Where to store SQLite temporary files. Defaults to 'MEMORY'. Setting this to FILESYSTEM can cause issues with larger queries or datasets. For details, see: https://www.sqlite.org/pragma.html#pragma_temp_store | - |
worker? | string | URL | (options) => Worker | SharedWorker | Allows you to override the default wasqlite db worker. You can either provide a path to the worker script or a factory method that returns a worker. | - |
WebStreamingSyncImplementationOptions
Internal
Extends
Extended by
Properties
WebSyncOptions
Properties
| Property | Type | Description |
|---|
worker? | string | URL | (options) => SharedWorker | Allows you to override the default sync worker. You can either provide a path to the worker script or a factory method that returns a worker. |
WithDiffOptions
Experimental
Options for TriggerDiffHandlerContext#withDiff.
Properties
| Property | Type | Description |
|---|
castOperationIdAsText? | boolean | Experimental If true, casts operation_id as TEXT in the internal CTE to preserve full 64-bit precision. Use this when you need to ensure operation_id is treated as a string to avoid precision loss for values exceeding JavaScript's Number.MAX_SAFE_INTEGER. When enabled, use TriggerDiffRecord to type the result correctly. |
WorkerDBOpenerOptions
Extends
Properties
Type Aliases
AbstractRemoteOptions
type AbstractRemoteOptions = {
fetchImplementation: | FetchImplementation
| FetchImplementationProvider;
fetchOptions: {};
socketUrlTransformer: (url) => string;
};
Type declaration
| Name | Type | Description |
|---|
fetchImplementation | | FetchImplementation | FetchImplementationProvider | Optionally provide the fetch implementation to use. Note that this usually needs to be bound to the global scope. Binding should be done before passing here. |
fetchOptions? | {} | Optional options to pass directly to all fetch calls. This can include fields such as dispatcher (e.g. for proxy support), cache, or any other fetch-compatible options. |
socketUrlTransformer | (url) => string | Transforms the PowerSync base URL which might contain http(s):// to the corresponding WebSocket variant e.g. ws(s):// |
ArrayComparatorOptions<ItemType>
type ArrayComparatorOptions<ItemType> = {
compareBy: (item) => string;
};
Options for ArrayComparator
Type Parameters
Type declaration
| Name | Type | Description |
|---|
compareBy | (item) => string | Returns a string to uniquely identify an item in the array. |
BaseColumnType<T>
type BaseColumnType<T> = {
type: ColumnType;
};
Type Parameters
| Type Parameter |
|---|
T extends number | string | null |
Type declaration
BaseListener
type BaseListener = Record<string, (...event) => any | undefined>;
BSONImplementation
type BSONImplementation = typeof BSON;
BucketOperationProgress
type BucketOperationProgress = Record<string, SavedProgress>;
ColumnsType
type ColumnsType = Record<string, BaseColumnType<any>>;
CrudUploadNotification
type CrudUploadNotification = {
crud_upload_completed: null;
};
Type declaration
| Name | Type |
|---|
crud_upload_completed | null |
DataStreamCallback()<Data>
type DataStreamCallback<Data> = (data) => Promise<void>;
Type Parameters
| Type Parameter | Default type |
|---|
Data extends any | any |
Parameters
Returns
Promise<void>
DataStreamOptions<ParsedData, SourceData>
type DataStreamOptions<ParsedData, SourceData> = {
closeOnError: boolean;
logger: ILogger;
mapLine: (line) => ParsedData;
pressure: {
highWaterMark: number;
lowWaterMark: number;
};
};
Type Parameters
| Type Parameter |
|---|
ParsedData |
SourceData |
Type declaration
| Name | Type | Description |
|---|
closeOnError? | boolean | Close the stream if any consumer throws an error |
logger? | ILogger | - |
mapLine? | (line) => ParsedData | - |
pressure? | { highWaterMark: number; lowWaterMark: number; } | - |
pressure.highWaterMark? | number | - |
pressure.lowWaterMark? | number | - |
DifferentialWatchedQuery<RowType>
type DifferentialWatchedQuery<RowType> = WatchedQuery<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>, DifferentialWatchedQueryListener<RowType>>;
Type Parameters
ExtractColumnValueType<T>
type ExtractColumnValueType<T> = T extends BaseColumnType<infer R> ? R : unknown;
Type Parameters
type ExtractedTriggerDiffRecord<T, TOperationId> = T & { [K in keyof Omit<BaseTriggerDiffRecord<TOperationId>, "id"> as `__${string & K}`]: TriggerDiffRecord<TOperationId>[K] } & {
__previous_value: string;
};
Experimental
Querying the DIFF table directly with TriggerDiffHandlerContext#withExtractedDiff will return records
with the tracked columns extracted from the JSON value.
This type represents the structure of such records.
Type declaration
| Name | Type |
|---|
__previous_value? | string |
Type Parameters
| Type Parameter | Default type | Description |
|---|
T | - | The type for the extracted columns from the tracked JSON value. |
TOperationId extends string | number | number | The type for operation_id. Defaults to number as returned by database queries. Use string for full 64-bit precision when using { castOperationIdAsText: true } option. |
Example
const diffs = await context.withExtractedDiff<ExtractedTriggerDiffRecord<{id: string, name: string}>>('SELECT * FROM DIFF');
const diffsWithString = await context.withExtractedDiff<ExtractedTriggerDiffRecord<{id: string, name: string}, string>>(
'SELECT * FROM DIFF',
undefined,
{ castOperationIdAsText: true }
);
FetchImplementation
type FetchImplementation = typeof fetch;
GetAllQueryOptions<RowType>
type GetAllQueryOptions<RowType> = {
mapper: (rawRow) => RowType;
parameters: ReadonlyArray<unknown>;
sql: string;
};
Options for GetAllQuery.
Type Parameters
| Type Parameter | Default type |
|---|
RowType | unknown |
Type declaration
| Name | Type | Description |
|---|
mapper? | (rawRow) => RowType | Optional mapper function to convert raw rows into the desired RowType. Example (rawRow) => ({ id: rawRow.id, created_at: new Date(rawRow.created_at), }) |
parameters? | ReadonlyArray<unknown> | - |
sql | string | - |
IndexShorthand
type IndexShorthand = Record<string, string[]>;
MutableWatchedQueryState<Data>
type MutableWatchedQueryState<Data> = { -readonly [P in keyof WatchedQueryState<Data>]: MutableDeep<WatchedQueryState<Data>[P]> };
Internal
Mutable version of WatchedQueryState.
This is used internally to allow updates to the state.
Type Parameters
OnTableChangeCallback()
type OnTableChangeCallback = (event) => void;
Internal
Parameters
Returns
void
OpenAsyncDatabaseConnection()<Config>
type OpenAsyncDatabaseConnection<Config> = (config) => AsyncDatabaseConnection;
Internal
Type Parameters
Parameters
| Parameter | Type |
|---|
config | Config |
Returns
AsyncDatabaseConnection
OpId
64-bit unsigned integer stored as a string in base-10.
Not sortable as a string.
OpTypeJSON
type OpTypeJSON = string;
PowerSyncConnectionOptions
type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, "serializedSchema">;
Configurable options to be used when connecting to the PowerSync
backend instance.
ProxiedQueryResult
type ProxiedQueryResult = Omit<QueryResult, "rows"> & {
rows: {
_array: any[];
length: number;
};
};
Internal
Proxied query result does not contain a function for accessing row values
Type declaration
| Name | Type |
|---|
rows | { _array: any[]; length: number; } |
rows._array | any[] |
rows.length | number |
QueryParam
type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
Query parameters for ArrayQueryDefinition#parameters
QueryResult
type QueryResult = {
insertId: number;
rows: {
_array: any[];
item: (idx) => any;
length: number;
};
rowsAffected: number;
};
Object returned by SQL Query executions.
Type declaration
| Name | Type | Description |
|---|
insertId? | number | Represents the auto-generated row id if applicable. |
rows? | { _array: any[]; item: (idx) => any; length: number; } | if status is undefined or 0 this object will contain the query results |
rows._array | any[] | Raw array with all dataset |
rows.item | (idx) => any | A convenience function to acess the index based the row object |
rows.length | number | The length of the dataset |
rowsAffected | number | Number of affected rows if result of a update query. |
RemoteConnector
type RemoteConnector = {
fetchCredentials: () => Promise<PowerSyncCredentials | null>;
invalidateCredentials: () => void;
};
Type declaration
| Name | Type |
|---|
fetchCredentials | () => Promise<PowerSyncCredentials | null> |
invalidateCredentials? | () => void |
RequiredPowerSyncConnectionOptions
type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
ResolvedWebSQLFlags
type ResolvedWebSQLFlags = Required<WebSQLFlags>;
RowType<T>
type RowType<T> = { [K in keyof T["columnMap"]]: ExtractColumnValueType<T["columnMap"][K]> } & {
id: string;
};
Type declaration
Type Parameters
| Type Parameter |
|---|
T extends TableV2<any> |
SavedProgress
type SavedProgress = {
atLast: number;
sinceLast: number;
};
Type declaration
| Name | Type |
|---|
atLast | number |
sinceLast | number |
SchemaTableType<S>
type SchemaTableType<S> = { [K in keyof S]: RowType<S[K]> };
Type Parameters
| Type Parameter |
|---|
S extends SchemaType |
SocketSyncStreamOptions
type SocketSyncStreamOptions = SyncStreamOptions & {
fetchStrategy: FetchStrategy;
};
Type declaration
SQLiteModule
type SQLiteModule = Parameters<typeof SQLite.Factory>[0];
Internal
StandardWatchedQuery<DataType>
type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
WatchedQuery returned from Query#watch.
Type Parameters
StreamingSyncLine
type StreamingSyncLine =
| StreamingSyncDataJSON
| StreamingSyncCheckpoint
| StreamingSyncCheckpointDiff
| StreamingSyncCheckpointComplete
| StreamingSyncCheckpointPartiallyComplete
| StreamingSyncKeepalive;
StreamingSyncLineOrCrudUploadComplete
type StreamingSyncLineOrCrudUploadComplete =
| StreamingSyncLine
| CrudUploadNotification;
StreamingSyncRequestParameterType
type StreamingSyncRequestParameterType = JSONValue;
SubscribedStream
type SubscribedStream = {
name: string;
params: Record<string, any> | null;
};
Type declaration
| Name | Type |
|---|
name | string |
params | Record<string, any> | null |
SyncDataBucketJSON
type SyncDataBucketJSON = {
after: string;
bucket: string;
data: OplogEntryJSON[];
has_more: boolean;
next_after: string;
};
Type declaration
| Name | Type |
|---|
after? | string |
bucket | string |
data | OplogEntryJSON[] |
has_more? | boolean |
next_after? | string |
SyncDataFlowStatus
type SyncDataFlowStatus = Partial<{
downloadError: Error;
downloading: boolean;
downloadProgress: InternalProgressInformation | null;
internalStreamSubscriptions: CoreStreamSubscription[] | null;
uploadError: Error;
uploading: boolean;
}>;
SyncRequest
type SyncRequest =
| ContinueCheckpointRequest
| SyncNewCheckpointRequest;
SyncStatusOptions
type SyncStatusOptions = {
clientImplementation: SyncClientImplementation;
connected: boolean;
connecting: boolean;
dataFlow: SyncDataFlowStatus;
hasSynced: boolean;
lastSyncedAt: Date;
priorityStatusEntries: SyncPriorityStatus[];
};
Type declaration
SyncStreamOptions
type SyncStreamOptions = {
abortSignal: AbortSignal;
data: StreamingSyncRequest;
fetchOptions: Request;
headers: Record<string, string>;
path: string;
};
Type declaration
| Name | Type |
|---|
abortSignal? | AbortSignal |
data | StreamingSyncRequest |
fetchOptions? | Request |
headers? | Record<string, string> |
path | string |
TriggerDiffRecord<TOperationId>
type TriggerDiffRecord<TOperationId> =
| TriggerDiffUpdateRecord<TOperationId>
| TriggerDiffInsertRecord<TOperationId>
| TriggerDiffDeleteRecord<TOperationId>;
Experimental
Diffs created by TriggerManager#createDiffTrigger are stored in a temporary table.
This is the record structure for all diff records.
Querying the DIFF table directly with TriggerDiffHandlerContext#withDiff will return records
with the structure of this type.
Type Parameters
| Type Parameter | Default type | Description |
|---|
TOperationId extends string | number | number | The type for operation_id. Defaults to number as returned by database queries. Use string for full 64-bit precision when using { castOperationIdAsText: true } option. |
Example
const diffs = await context.withDiff<TriggerDiffRecord>('SELECT * FROM DIFF');
const diffsWithString = await context.withDiff<TriggerDiffRecord<string>>(
'SELECT * FROM DIFF',
undefined,
{ castOperationIdAsText: true }
);
TriggerRemoveCallback()
type TriggerRemoveCallback = () => Promise<void>;
Experimental
Callback to drop a trigger after it has been created.
Returns
Promise<void>
WASQLiteBroadCastTableUpdateEvent
type WASQLiteBroadCastTableUpdateEvent = {
changedTables: Set<string>;
connectionId: number;
};
Internal
Type declaration
| Name | Type |
|---|
changedTables | Set<string> |
connectionId | number |
WASQLiteConnectionListener
type WASQLiteConnectionListener = {
holdOverwritten: (holdId) => Promise<void>;
tablesUpdated: (event) => void;
};
Internal
Type declaration
| Name | Type | Description |
|---|
holdOverwritten | (holdId) => Promise<void> | Triggered when an active hold is overwritten by a new hold. This is most likely to happen when a shared connection has been closed without releasing the hold. This listener can be used to cleanup any resources associated with the previous hold. |
tablesUpdated | (event) => void | - |
WASQLiteFlags
type WASQLiteFlags = WebSQLFlags;
These flags are the same as WebSQLFlags.
This export is maintained only for API consistency
WASQLiteModuleFactory()
type WASQLiteModuleFactory = (options) => Promise<{
module: SQLiteModule;
vfs: SQLiteVFS;
}>;
Internal
Parameters
Returns
Promise<{
module: SQLiteModule;
vfs: SQLiteVFS;
}>
WASQLiteModuleFactoryOptions
type WASQLiteModuleFactoryOptions = {
dbFileName: string;
encryptionKey: string;
};
Internal
Type declaration
| Name | Type |
|---|
dbFileName | string |
encryptionKey? | string |
WebPowerSyncDatabaseOptions
type WebPowerSyncDatabaseOptions = WithWebSyncOptions<WithWebFlags<PowerSyncDatabaseOptions>>;
WebPowerSyncDatabaseOptionsWithAdapter
type WebPowerSyncDatabaseOptionsWithAdapter = WithWebSyncOptions<WithWebFlags<PowerSyncDatabaseOptionsWithDBAdapter>>;
WebPowerSyncDatabaseOptionsWithOpenFactory
type WebPowerSyncDatabaseOptionsWithOpenFactory = WithWebSyncOptions<WithWebFlags<PowerSyncDatabaseOptionsWithOpenFactory>>;
WebPowerSyncDatabaseOptionsWithSettings
type WebPowerSyncDatabaseOptionsWithSettings = WithWebSyncOptions<WithWebFlags<WithWebEncryptionOptions<PowerSyncDatabaseOptionsWithSettings>>>;
Variables
column
const column: {
integer: BaseColumnType<number | null>;
real: BaseColumnType<number | null>;
text: BaseColumnType<string | null>;
};
Type declaration
DEFAULT_CACHE_SIZE_KB
const DEFAULT_CACHE_SIZE_KB: number;
DEFAULT_CRUD_BATCH_LIMIT
const DEFAULT_CRUD_BATCH_LIMIT: 100 = 100;
DEFAULT_CRUD_UPLOAD_THROTTLE_MS
const DEFAULT_CRUD_UPLOAD_THROTTLE_MS: 1000 = 1000;
DEFAULT_INDEX_COLUMN_OPTIONS
const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions>;
DEFAULT_INDEX_OPTIONS
const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions>;
DEFAULT_LOCK_TIMEOUT_MS
const DEFAULT_LOCK_TIMEOUT_MS: 120000 = 120000;
Requesting nested or recursive locks can block the application in some circumstances.
This default lock timeout will act as a failsafe to throw an error if a lock cannot
be obtained.
DEFAULT_MODULE_FACTORIES
const DEFAULT_MODULE_FACTORIES: {
AccessHandlePoolVFS: (options) => Promise<{
module: any;
vfs: any;
}>;
IDBBatchAtomicVFS: (options) => Promise<{
module: any;
vfs: any;
}>;
OPFSCoopSyncVFS: (options) => Promise<{
module: any;
vfs: any;
}>;
};
Internal
Type declaration
| Name | Type |
|---|
AccessHandlePoolVFS | (options) => Promise<{ module: any; vfs: any; }> |
IDBBatchAtomicVFS | (options) => Promise<{ module: any; vfs: any; }> |
OPFSCoopSyncVFS | (options) => Promise<{ module: any; vfs: any; }> |
DEFAULT_POWERSYNC_CLOSE_OPTIONS
const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
DEFAULT_POWERSYNC_DB_OPTIONS
const DEFAULT_POWERSYNC_DB_OPTIONS: {
crudUploadThrottleMs: number;
retryDelayMs: number;
};
Type declaration
| Name | Type |
|---|
crudUploadThrottleMs | number |
retryDelayMs | number |
DEFAULT_POWERSYNC_FLAGS
const DEFAULT_POWERSYNC_FLAGS: Required<WebPowerSyncFlags>;
DEFAULT_PRESSURE_LIMITS
const DEFAULT_PRESSURE_LIMITS: {
highWater: number;
lowWater: number;
};
Type declaration
| Name | Type |
|---|
highWater | number |
lowWater | number |
DEFAULT_REMOTE_LOGGER
const DEFAULT_REMOTE_LOGGER: Logger.ILogger;
DEFAULT_REMOTE_OPTIONS
const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions;
DEFAULT_RETRY_DELAY_MS
const DEFAULT_RETRY_DELAY_MS: 5000 = 5000;
DEFAULT_ROW_COMPARATOR
const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any>;
Default implementation of the DifferentialWatchedQueryComparator for watched queries.
It keys items by their id property if available, alternatively it uses JSON stringification
of the entire item for the key and comparison.
DEFAULT_STREAM_CONNECTION_OPTIONS
const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions;
DEFAULT_STREAMING_SYNC_OPTIONS
const DEFAULT_STREAMING_SYNC_OPTIONS: {
crudUploadThrottleMs: number;
retryDelayMs: number;
};
Type declaration
| Name | Type |
|---|
crudUploadThrottleMs | number |
retryDelayMs | number |
DEFAULT_SYNC_CLIENT_IMPLEMENTATION
const DEFAULT_SYNC_CLIENT_IMPLEMENTATION: JAVASCRIPT = SyncClientImplementation.JAVASCRIPT;
The default SyncClientImplementation to use.
Please use this field instead of SyncClientImplementation.JAVASCRIPT directly. A future version
of the PowerSync SDK will enable SyncClientImplementation.RUST by default and remove the JavaScript
option.
DEFAULT_TABLE_OPTIONS
const DEFAULT_TABLE_OPTIONS: {
ignoreEmptyUpdates: boolean;
indexes: never[];
insertOnly: boolean;
localOnly: boolean;
trackMetadata: boolean;
trackPrevious: boolean;
};
Type declaration
| Name | Type |
|---|
ignoreEmptyUpdates | boolean |
indexes | never[] |
insertOnly | boolean |
localOnly | boolean |
trackMetadata | boolean |
trackPrevious | boolean |
DEFAULT_WATCH_QUERY_OPTIONS
const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions;
DEFAULT_WATCH_THROTTLE_MS
const DEFAULT_WATCH_THROTTLE_MS: 30 = 30;
DEFAULT_WEB_SQL_FLAGS
const DEFAULT_WEB_SQL_FLAGS: ResolvedWebSQLFlags;
EMPTY_DIFFERENTIAL
const EMPTY_DIFFERENTIAL: {
added: never[];
all: never[];
removed: never[];
unchanged: never[];
updated: never[];
};
An empty differential result set.
This is used as the initial state for differential incrementally watched queries.
Type declaration
| Name | Type |
|---|
added | never[] |
all | never[] |
removed | never[] |
unchanged | never[] |
updated | never[] |
FalsyComparator
const FalsyComparator: WatchedQueryComparator<unknown>;
Watched query comparator that always reports changed result sets.
InvalidSQLCharacters
const InvalidSQLCharacters: RegExp;
LogLevel
const LogLevel: {
DEBUG: Logger.ILogLevel;
ERROR: Logger.ILogLevel;
INFO: Logger.ILogLevel;
OFF: Logger.ILogLevel;
TIME: Logger.ILogLevel;
TRACE: Logger.ILogLevel;
WARN: Logger.ILogLevel;
};
Type declaration
| Name | Type |
|---|
DEBUG | Logger.ILogLevel |
ERROR | Logger.ILogLevel |
INFO | Logger.ILogLevel |
OFF | Logger.ILogLevel |
TIME | Logger.ILogLevel |
TRACE | Logger.ILogLevel |
WARN | Logger.ILogLevel |
MAX_AMOUNT_OF_COLUMNS
const MAX_AMOUNT_OF_COLUMNS: 1999 = 1999;
MAX_OP_ID
const MAX_OP_ID: "9223372036854775807" = "9223372036854775807";
Functions