diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 8e2de3fc0..928fd2757 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -1,10 +1,10 @@ -import { themes as prismThemes } from 'prism-react-renderer'; -import type { TypeDocOptionMap } from 'typedoc'; -import type { Config } from '@docusaurus/types'; import type * as Preset from '@docusaurus/preset-classic'; +import type { Config } from '@docusaurus/types'; import type { PluginOptions } from 'docusaurus-plugin-typedoc'; -import { DOC_FOLDER, packageMap } from './utils/packageMap'; import 'dotenv/config'; +import { themes as prismThemes } from 'prism-react-renderer'; +import type { TypeDocOptionMap } from 'typedoc'; +import { DOC_FOLDER, packageMap } from './utils/packageMap'; const PROJECT_NAME = process.env.GH_PROJECT_NAME; @@ -21,12 +21,13 @@ const plugins = Object.entries(packageMap).map(([id, config]) => [ enumMembersFormat: 'table', excludeProtected: true, excludePrivate: true, + excludeInternal: true, indexFormat: 'table', disableSources: true, expandObjects: true, useCodeBlocks: true, typeDeclarationFormat: 'table', - membersWithOwnFile: ['Class', 'Enum', 'Function'], + membersWithOwnFile: ['Class', 'Enum', 'Function', 'Interface'], textContentMappings: { 'title.memberPage': '{name}' } @@ -155,8 +156,8 @@ const config: Config = { darkTheme: prismThemes.dracula }, future: { - experimental_faster: true, - }, + experimental_faster: true + } } satisfies Preset.ThemeConfig }; diff --git a/packages/common/src/client/sync/bucket/BucketStorageAdapter.ts b/packages/common/src/client/sync/bucket/BucketStorageAdapter.ts index ecd6c7ef4..1deeb6f7d 100644 --- a/packages/common/src/client/sync/bucket/BucketStorageAdapter.ts +++ b/packages/common/src/client/sync/bucket/BucketStorageAdapter.ts @@ -3,40 +3,64 @@ import { CrudBatch } from './CrudBatch.js'; import { CrudEntry, OpId } from './CrudEntry.js'; import { SyncDataBatch } from './SyncDataBatch.js'; +/** + * @internal + */ export interface BucketDescription { name: string; priority: number; } +/** + * @internal + */ export interface Checkpoint { last_op_id: OpId; buckets: BucketChecksum[]; write_checkpoint?: string; } +/** + * @internal + */ export interface BucketState { bucket: string; op_id: string; } +/** + * @internal + */ export interface ChecksumCache { checksums: Map; lastOpId: OpId; } +/** + * @internal + */ export interface SyncLocalDatabaseResult { ready: boolean; checkpointValid: boolean; checkpointFailures?: string[]; } +/** + * @internal + */ export type SavedProgress = { atLast: number; sinceLast: number; }; +/** + * @internal + */ export type BucketOperationProgress = Record; +/** + * @internal + */ export interface BucketChecksum { bucket: string; priority?: number; @@ -51,6 +75,9 @@ export interface BucketChecksum { count?: number; } +/** + * @internal + */ export enum PSInternalTable { DATA = 'ps_data', CRUD = 'ps_crud', @@ -59,6 +86,9 @@ export enum PSInternalTable { UNTYPED = 'ps_untyped' } +/** + * @internal + */ export enum PowerSyncControlCommand { PROCESS_TEXT_LINE = 'line_text', PROCESS_BSON_LINE = 'line_binary', @@ -68,10 +98,16 @@ export enum PowerSyncControlCommand { NOTIFY_CRUD_UPLOAD_COMPLETED = 'completed_upload' } +/** + * @internal + */ export interface BucketStorageListener extends BaseListener { crudUpdate: () => void; } +/** + * @internal + */ export interface BucketStorageAdapter extends BaseObserver, Disposable { init(): Promise; saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise; diff --git a/packages/common/src/client/sync/bucket/OpType.ts b/packages/common/src/client/sync/bucket/OpType.ts index c39b8b309..23f6f2d3b 100644 --- a/packages/common/src/client/sync/bucket/OpType.ts +++ b/packages/common/src/client/sync/bucket/OpType.ts @@ -1,3 +1,6 @@ +/** + * @internal + */ export enum OpTypeEnum { CLEAR = 1, MOVE = 2, @@ -5,10 +8,14 @@ export enum OpTypeEnum { REMOVE = 4 } +/** + * @internal + */ export type OpTypeJSON = string; /** * Used internally for sync buckets. + * @internal */ export class OpType { static fromJSON(jsonValue: OpTypeJSON) { diff --git a/packages/common/src/client/sync/bucket/OplogEntry.ts b/packages/common/src/client/sync/bucket/OplogEntry.ts index a8e3893ab..8f2ac7c9e 100644 --- a/packages/common/src/client/sync/bucket/OplogEntry.ts +++ b/packages/common/src/client/sync/bucket/OplogEntry.ts @@ -1,6 +1,9 @@ import { OpId } from './CrudEntry.js'; import { OpType, OpTypeJSON } from './OpType.js'; +/** + * @internal + */ export interface OplogEntryJSON { checksum: number; data?: string; @@ -11,6 +14,9 @@ export interface OplogEntryJSON { subkey?: string; } +/** + * @internal + */ export class OplogEntry { static fromRow(row: OplogEntryJSON) { return new OplogEntry( diff --git a/packages/common/src/client/sync/bucket/SqliteBucketStorage.ts b/packages/common/src/client/sync/bucket/SqliteBucketStorage.ts index 4615db6e5..be55bad3c 100644 --- a/packages/common/src/client/sync/bucket/SqliteBucketStorage.ts +++ b/packages/common/src/client/sync/bucket/SqliteBucketStorage.ts @@ -17,6 +17,9 @@ import { CrudBatch } from './CrudBatch.js'; import { CrudEntry, CrudEntryJSON } from './CrudEntry.js'; import { SyncDataBatch } from './SyncDataBatch.js'; +/** + * @internal + */ export class SqliteBucketStorage extends BaseObserver implements BucketStorageAdapter { public tableNames: Set; private _hasCompletedSync: boolean; diff --git a/packages/common/src/client/sync/bucket/SyncDataBatch.ts b/packages/common/src/client/sync/bucket/SyncDataBatch.ts index 3432f58ee..0a12e3fe6 100644 --- a/packages/common/src/client/sync/bucket/SyncDataBatch.ts +++ b/packages/common/src/client/sync/bucket/SyncDataBatch.ts @@ -2,6 +2,9 @@ import { SyncDataBucket } from './SyncDataBucket.js'; // TODO JSON +/** + * @internal + */ export class SyncDataBatch { static fromJSON(json: any) { return new SyncDataBatch(json.buckets.map((bucket: any) => SyncDataBucket.fromRow(bucket))); diff --git a/packages/common/src/client/sync/bucket/SyncDataBucket.ts b/packages/common/src/client/sync/bucket/SyncDataBucket.ts index 45fe8de26..eb966d05f 100644 --- a/packages/common/src/client/sync/bucket/SyncDataBucket.ts +++ b/packages/common/src/client/sync/bucket/SyncDataBucket.ts @@ -1,6 +1,9 @@ import { OpId } from './CrudEntry.js'; import { OplogEntry, OplogEntryJSON } from './OplogEntry.js'; +/** + * @internal + */ export type SyncDataBucketJSON = { bucket: string; has_more?: boolean; @@ -9,6 +12,9 @@ export type SyncDataBucketJSON = { data: OplogEntryJSON[]; }; +/** + * @internal + */ export class SyncDataBucket { static fromRow(row: SyncDataBucketJSON) { return new SyncDataBucket( diff --git a/packages/common/src/client/sync/stream/AbstractRemote.ts b/packages/common/src/client/sync/stream/AbstractRemote.ts index f0de66d00..e8d9774d8 100644 --- a/packages/common/src/client/sync/stream/AbstractRemote.ts +++ b/packages/common/src/client/sync/stream/AbstractRemote.ts @@ -7,15 +7,17 @@ import PACKAGE from '../../../../package.json' with { type: 'json' }; import { AbortOperation } from '../../../utils/AbortOperation.js'; import { DataStream } from '../../../utils/DataStream.js'; import { PowerSyncCredentials } from '../../connection/PowerSyncCredentials.js'; -import { - StreamingSyncLine, - StreamingSyncLineOrCrudUploadComplete, - StreamingSyncRequest -} from './streaming-sync-types.js'; +import { StreamingSyncRequest } from './streaming-sync-types.js'; import { WebsocketClientTransport } from './WebsocketClientTransport.js'; +/** + * @internal + */ export type BSONImplementation = typeof BSON; +/** + * @internal + */ export type RemoteConnector = { fetchCredentials: () => Promise; invalidateCredentials?: () => void; @@ -39,6 +41,9 @@ const KEEP_ALIVE_LIFETIME_MS = 90_000; export const DEFAULT_REMOTE_LOGGER = Logger.get('PowerSyncRemote'); +/** + * @internal + */ export type SyncStreamOptions = { path: string; data: StreamingSyncRequest; @@ -65,6 +70,9 @@ export type SocketSyncStreamOptions = SyncStreamOptions & { fetchStrategy: FetchStrategy; }; +/** + * @internal + */ export type FetchImplementation = typeof fetch; /** @@ -72,6 +80,7 @@ export type FetchImplementation = typeof fetch; * The class wrapper is used to distinguish the fetchImplementation * option in [AbstractRemoteOptions] from the general fetch method * which is typeof "function" + * @internal */ export class FetchImplementationProvider { getFetch(): FetchImplementation { @@ -79,6 +88,9 @@ export class FetchImplementationProvider { } } +/** + * @internal + */ export type AbstractRemoteOptions = { /** * Transforms the PowerSync base URL which might contain diff --git a/packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts b/packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts index e3fea79b6..795fff91d 100644 --- a/packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts +++ b/packages/common/src/client/sync/stream/AbstractStreamingSyncImplementation.ts @@ -1,11 +1,11 @@ import Logger, { ILogger } from 'js-logger'; -import { DataStream } from '../../../utils/DataStream.js'; -import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js'; import { FULL_SYNC_PRIORITY, InternalProgressInformation } from '../../../db/crud/SyncProgress.js'; import * as sync_status from '../../../db/crud/SyncStatus.js'; +import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js'; import { AbortOperation } from '../../../utils/AbortOperation.js'; import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js'; +import { DataStream } from '../../../utils/DataStream.js'; import { throttleLeadingTrailing } from '../../../utils/async.js'; import { BucketChecksum, @@ -17,6 +17,7 @@ import { import { CrudEntry } from '../bucket/CrudEntry.js'; import { SyncDataBucket } from '../bucket/SyncDataBucket.js'; import { AbstractRemote, FetchStrategy, SyncStreamOptions } from './AbstractRemote.js'; +import { EstablishSyncStream, Instruction, SyncPriorityStatus } from './core-instruction.js'; import { BucketRequest, CrudUploadNotification, @@ -30,8 +31,10 @@ import { isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData } from './streaming-sync-types.js'; -import { EstablishSyncStream, Instruction, SyncPriorityStatus } from './core-instruction.js'; +/** + * @internal + */ export enum LockType { CRUD = 'crud', SYNC = 'sync' @@ -88,6 +91,8 @@ export const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.JAVAS /** * Abstract Lock to be implemented by various JS environments + * + * @internal */ export interface LockOptions { callback: () => Promise; @@ -95,6 +100,9 @@ export interface LockOptions { signal?: AbortSignal; } +/** + * @internal + */ export interface AbstractStreamingSyncImplementationOptions extends AdditionalConnectionOptions { adapter: BucketStorageAdapter; uploadCrud: () => Promise; @@ -125,6 +133,9 @@ export interface StreamingSyncImplementationListener extends BaseListener { */ export type PowerSyncConnectionOptions = Omit; +/** + * @internal + */ export interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {} /** @internal */ @@ -208,6 +219,9 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = { crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS }; +/** + * @internal + */ export type RequiredPowerSyncConnectionOptions = Required; export const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions = { diff --git a/packages/common/src/client/sync/stream/streaming-sync-types.ts b/packages/common/src/client/sync/stream/streaming-sync-types.ts index fdb73f360..a359f0e94 100644 --- a/packages/common/src/client/sync/stream/streaming-sync-types.ts +++ b/packages/common/src/client/sync/stream/streaming-sync-types.ts @@ -4,6 +4,7 @@ import { SyncDataBucketJSON } from '../bucket/SyncDataBucket.js'; /** * For sync2.json + * @internal */ export interface ContinueCheckpointRequest { /** @@ -16,6 +17,9 @@ export interface ContinueCheckpointRequest { limit?: number; } +/** + * @internal + */ export interface SyncNewCheckpointRequest { /** * Existing bucket states. Used if include_data is specified. @@ -37,8 +41,14 @@ export interface SyncNewCheckpointRequest { limit?: number; } +/** + * @internal + */ export type SyncRequest = ContinueCheckpointRequest | SyncNewCheckpointRequest; +/** + * @internal + */ export interface SyncResponse { /** * Data for the buckets returned. May not have an an entry for each bucket in the request. @@ -62,8 +72,14 @@ interface JSONObject { } type JSONArray = JSONValue[]; +/** + * @internal + */ export type StreamingSyncRequestParameterType = JSONValue; +/** + * @internal + */ export interface StreamingSyncRequest { /** * Existing bucket states. @@ -93,10 +109,16 @@ export interface StreamingSyncRequest { client_id?: string; } +/** + * @internal + */ export interface StreamingSyncCheckpoint { checkpoint: Checkpoint; } +/** + * @internal + */ export interface StreamingSyncCheckpointDiff { checkpoint_diff: { last_op_id: OpId; @@ -106,16 +128,25 @@ export interface StreamingSyncCheckpointDiff { }; } +/** + * @internal + */ export interface StreamingSyncDataJSON { data: SyncDataBucketJSON; } +/** + * @internal + */ export interface StreamingSyncCheckpointComplete { checkpoint_complete: { last_op_id: OpId; }; } +/** + * @internal + */ export interface StreamingSyncCheckpointPartiallyComplete { partial_checkpoint_complete: { priority: number; @@ -123,11 +154,17 @@ export interface StreamingSyncCheckpointPartiallyComplete { }; } +/** + * @internal + */ export interface StreamingSyncKeepalive { /** If specified, token expires in this many seconds. */ token_expires_in: number; } +/** + * @internal + */ export type StreamingSyncLine = | StreamingSyncDataJSON | StreamingSyncCheckpoint @@ -136,10 +173,20 @@ export type StreamingSyncLine = | StreamingSyncCheckpointPartiallyComplete | StreamingSyncKeepalive; +/** + * @internal + */ + export type CrudUploadNotification = { crud_upload_completed: null }; +/** + * @internal + */ export type StreamingSyncLineOrCrudUploadComplete = StreamingSyncLine | CrudUploadNotification; +/** + * @internal + */ export interface BucketRequest { name: string; @@ -149,32 +196,53 @@ export interface BucketRequest { after: OpId; } +/** + * @internal + */ export function isStreamingSyncData(line: StreamingSyncLine): line is StreamingSyncDataJSON { return (line as StreamingSyncDataJSON).data != null; } +/** + * @internal + */ export function isStreamingKeepalive(line: StreamingSyncLine): line is StreamingSyncKeepalive { return (line as StreamingSyncKeepalive).token_expires_in != null; } +/** + * @internal + */ export function isStreamingSyncCheckpoint(line: StreamingSyncLine): line is StreamingSyncCheckpoint { return (line as StreamingSyncCheckpoint).checkpoint != null; } +/** + * @internal + */ export function isStreamingSyncCheckpointComplete(line: StreamingSyncLine): line is StreamingSyncCheckpointComplete { return (line as StreamingSyncCheckpointComplete).checkpoint_complete != null; } +/** + * @internal + */ export function isStreamingSyncCheckpointPartiallyComplete( line: StreamingSyncLine ): line is StreamingSyncCheckpointPartiallyComplete { return (line as StreamingSyncCheckpointPartiallyComplete).partial_checkpoint_complete != null; } +/** + * @internal + */ export function isStreamingSyncCheckpointDiff(line: StreamingSyncLine): line is StreamingSyncCheckpointDiff { return (line as StreamingSyncCheckpointDiff).checkpoint_diff != null; } +/** + * @internal + */ export function isContinueCheckpointRequest(request: SyncRequest): request is ContinueCheckpointRequest { return ( Array.isArray((request as ContinueCheckpointRequest).buckets) && @@ -182,17 +250,25 @@ export function isContinueCheckpointRequest(request: SyncRequest): request is Co ); } +/** + * @internal + */ + export function isSyncNewCheckpointRequest(request: SyncRequest): request is SyncNewCheckpointRequest { return typeof (request as SyncNewCheckpointRequest).request_checkpoint == 'object'; } /** * For crud.json + * @internal */ export interface CrudRequest { data: CrudEntry[]; } +/** + * @internal + */ export interface CrudResponse { /** * A sync response with a checkpoint >= this checkpoint would contain all the changes in this request. diff --git a/packages/common/src/utils/BaseObserver.ts b/packages/common/src/utils/BaseObserver.ts index df56e9e61..7638e5802 100644 --- a/packages/common/src/utils/BaseObserver.ts +++ b/packages/common/src/utils/BaseObserver.ts @@ -1,15 +1,27 @@ +/** + * @internal + */ export interface Disposable { dispose: () => Promise; } +/** + * @internal + */ export interface BaseObserverInterface { registerListener(listener: Partial): () => void; } +/** + * @internal + */ export type BaseListener = { [key: string]: ((...event: any) => any) | undefined; }; +/** + * @internal + */ export class BaseObserver implements BaseObserverInterface { protected listeners = new Set>(); diff --git a/packages/common/src/utils/DataStream.ts b/packages/common/src/utils/DataStream.ts index 410b1066b..ebf18c087 100644 --- a/packages/common/src/utils/DataStream.ts +++ b/packages/common/src/utils/DataStream.ts @@ -1,6 +1,9 @@ import Logger, { ILogger } from 'js-logger'; import { BaseListener, BaseObserver } from './BaseObserver.js'; +/** + * @internal + */ export type DataStreamOptions = { mapLine?: (line: SourceData) => ParsedData; @@ -15,8 +18,14 @@ export type DataStreamOptions = { logger?: ILogger; }; +/** + * @internal + */ export type DataStreamCallback = (data: Data) => Promise; +/** + * @internal + */ export interface DataStreamListener extends BaseListener { data: (data: Data) => Promise; closed: () => void; @@ -25,6 +34,9 @@ export interface DataStreamListener extends BaseListener lowWater: () => Promise; } +/** + * @internal + */ export const DEFAULT_PRESSURE_LIMITS = { highWater: 10, lowWater: 0 @@ -34,6 +46,7 @@ export const DEFAULT_PRESSURE_LIMITS = { * A very basic implementation of a data stream with backpressure support which does not use * native JS streams or async iterators. * This is handy for environments such as React Native which need polyfills for the above. + * @internal */ export class DataStream extends BaseObserver> { dataQueue: SourceData[];