@casual-simulation/aux-common 3.3.11 → 3.3.13

package/documents/SharedDocument.d.ts

@@ -0,0 +1,449 @@
+import { ClientError } from '../websockets';
+import { Action, CurrentVersion, StatusUpdate } from '../common';
+import { Observable, SubscriptionLike } from 'rxjs';
+import { InstUpdate } from '../bots';
+/**
+ * Defines an interface for objects that are able to synchronize data between multiple clients.
+ */
+export interface SharedDocument extends SubscriptionLike {
+    /**
+     * The name of the record that the document is stored under.
+     * If null, then the document is public.
+     */
+    recordName: string | null;
+    /**
+     * The address of the document.
+     * If null, then the document is stored locally.
+     */
+    address: string | null;
+    /**
+     * The branch that was loaded for the document.
+     */
+    branch: string;
+    /**
+     * The ID of the remote client that the document is associated with.
+     */
+    clientId: number;
+    /**
+     * Gets an observable list that resolves whenever the partition state version is updated.
+     */
+    onVersionUpdated: Observable<CurrentVersion>;
+    /**
+     * Gets an observable list of errors from the partition.
+     * That is, errors that the client cannot handle.
+     */
+    onError: Observable<any>;
+    /**
+     * Gets the observable list of remote events from the partition.
+     */
+    onEvents: Observable<Action[]>;
+    /**
+     * Gets the observable list of status updates from the partition.
+     */
+    onStatusUpdated: Observable<StatusUpdate>;
+    /**
+     * Gets the observable list of client errors from the document.
+     * That is, errors that were caused by the client's behavior.
+     */
+    onClientError: Observable<ClientError>;
+    /**
+     * Tells the document to connect to its backing store.
+     */
+    connect(): void;
+    /**
+     * Gets a top-level map that can be used to store key/value data.
+     * @param name The name of the map.
+     */
+    getMap<T = any>(name: string): SharedMap<T>;
+    /**
+     * Gets a top-level array that can be used to store a list of items.
+     * @param name The name of the array.
+     */
+    getArray<T = any>(name: string): SharedArray<T>;
+    /**
+     * Gets a top-level text object that can be used to store rich text.
+     * @param name The name of the text.
+     */
+    getText(name: string): SharedText;
+    /**
+     * Creates a new map that can be shared between multiple clients.
+     */
+    createMap<T = any>(): SharedMap<T>;
+    /**
+     * Creates a new array that can be shared between multiple clients.
+     */
+    createArray<T = any>(): SharedArray<T>;
+    /**
+     * Batches changes that occur within the given callback function into a single transaction.
+     * This makes multiple updates more efficient.
+     * @param callback The function to execute.
+     */
+    transact(callback: () => void): void;
+    /**
+     * Gets the update that represents the current state of the document.
+     */
+    getStateUpdate(): InstUpdate;
+    /**
+     * Applies the given updates to the document.
+     * @param updates The updates to apply.
+     */
+    applyStateUpdates(updates: InstUpdate[]): void;
+}
+export type SharedType = SharedMap | SharedArray | SharedText;
+export type SharedTypeChanges = SharedMapChanges<any> | SharedArrayChanges<any> | SharedTextChanges;
+export interface SharedTypeBase {
+    /**
+     * The document that the map is associated with.
+     */
+    readonly doc: SharedDocument;
+    /**
+     * The type that this map is stored in.
+     */
+    readonly parent: SharedType | null;
+}
+/**
+ * Defines a map that can be shared between multiple clients.
+ */
+export interface SharedMap<T = any> extends SharedTypeBase {
+    /**
+     * Gets the number of keys that are in the map.
+     */
+    readonly size: number;
+    /**
+     * Sets the given key to the given value.
+     * @param key The key to set.
+     * @param value The value to set.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Gets the value for the given key.
+     * @param key The key to get.
+     */
+    get(key: string): T;
+    /**
+     * Deletes the given key from the map.
+     * @param key Deletes the given key.
+     */
+    delete(key: string): void;
+    /**
+     * Determines if the given key exists in the map.
+     * @param key The key.
+     */
+    has(key: string): boolean;
+    /**
+     * Clears the map.
+     */
+    clear(): void;
+    /**
+     * Creates a new map that is a clone of this map.
+     */
+    clone(): SharedMap;
+    /**
+     * Transforms this map into an object that can be serialized to JSON.
+     */
+    toJSON(): {
+        [key: string]: T;
+    };
+    /**
+     * Execute the provided function once on every key/value pair.
+     * @param callback The function to execute.
+     */
+    forEach(callback: (value: T, key: string, map: SharedMap<T>) => void): void;
+    /**
+     * Gets an iterator for the key/value pairs stored in the map.
+     */
+    [Symbol.iterator](): IterableIterator<[string, T]>;
+    /**
+     * Gets an iterator for the key/value pairs stored in the map.
+     */
+    entries(): IterableIterator<[string, T]>;
+    /**
+     * Gets an iterator for the keys stored in the map.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Gets an iterator for the values stored in the map.
+     */
+    values(): IterableIterator<T>;
+    /**
+     * Gets an observable that resolves whenever the map is changed.
+     */
+    readonly changes: Observable<SharedMapChanges<T>>;
+    /**
+     * Gets an observable that resolves whenever this map or any children are changed.
+     */
+    readonly deepChanges: Observable<SharedTypeChanges[]>;
+}
+/**
+ * Defines an array that can be shared between multiple clients.
+ */
+export interface SharedArray<T = any> extends SharedTypeBase {
+    /**
+     * Gets the number of elements in the array.
+     */
+    readonly length: number;
+    /**
+     * Gets the number of elements in the array.
+     */
+    readonly size: number;
+    /**
+     * Insert items at the given index.
+     * @param index The index to insert the items at. Items at or after this index will be pushed back to make space for the new items. If the index is greater than the length of the array, then the items are appended to the end of the array.
+     * @param items The items to insert.
+     */
+    insert(index: number, items: T[]): void;
+    /**
+     * Deletes the given number of items, starting at the given index.
+     * @param index The index of the first item to be deleted.
+     * @param count The number of items to delete.
+     */
+    delete(index: number, count: number): void;
+    /**
+     * Applies the given delta to the array.
+     * @param delta The delta to apply.
+     */
+    applyDelta(delta: SharedArrayDelta<T>): void;
+    /**
+     * Append items to the end of the array.
+     * @param items The items to add.
+     */
+    push(...items: T[]): void;
+    /**
+     * Removes the last item from the array and returns it.
+     */
+    pop(): T | undefined;
+    /**
+     * Prepend items to the beginning of the array.
+     * @param items The items to add.
+     */
+    unshift(...items: T[]): void;
+    /**
+     * Removes the first item from the array and returns it.
+     */
+    shift(): T | undefined;
+    /**
+     * Gets the item at the given index.
+     * @param index The index to get.
+     */
+    get(index: number): T;
+    /**
+     * Gets a range of items from the array.
+     * Negative indexes can be used to start from the end of the array.
+     * @param start The index of the first item to retrieve.
+     * @param end The index of the last item to retrieve.
+     */
+    slice(start?: number, end?: number): T[];
+    /**
+     * Changes the contents of the array by removing or replacing existing elements and/or adding new elements.
+     * Returns a JavaScript array containing the removed elements.
+     * @param start The index at which to start changing the array.
+     * @param deleteCount The number of elements in the array to remove from start.
+     * @param items The elements to add to the array.
+     */
+    splice(start: number, deleteCount: number, ...items: T[]): T[];
+    /**
+     * Creates a new JavaScript array that is a clone of this array.
+     */
+    toArray(): T[];
+    /**
+     * Transforms this map into an array that can be serialized to JSON.
+     */
+    toJSON(): T[];
+    /**
+     * Execute the given callback function for each item in the array.
+     * @param callback The function to execute.
+     */
+    forEach(callback: (value: T, index: number, array: SharedArray<T>) => void): void;
+    /**
+     * Creates a new JavaScript array with the results of calling a provided function on every element in this array.
+     * @param callback The function to execute.
+     */
+    map(callback: (value: T, index: number, array: SharedArray<T>) => T): T[];
+    /**
+     * Creates a new JavaScript array with all elements that pass the test implemented by the provided function.
+     * @param predicate The function to execute.
+     */
+    filter(predicate: (value: T, index: number, array: SharedArray<T>) => boolean): T[];
+    /**
+     * Gets an iterator for the items in the array.
+     */
+    [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * Creates a new shared array that is a clone of this array.
+     */
+    clone(): SharedArray<T>;
+    /**
+     * Gets an observable that resolves whenever the array is changed.
+     */
+    readonly changes: Observable<SharedArrayChanges<T>>;
+    /**
+     * Gets an observable that resolves whenever this array or any children are changed.
+     */
+    readonly deepChanges: Observable<SharedTypeChanges[]>;
+}
+/**
+ * Defines an object that represents rich text that can be shared between multiple clients.
+ */
+export interface SharedText extends SharedTypeBase {
+    /**
+     * Gets the length of the string in UTF-16 code units.
+     */
+    readonly length: number;
+    /**
+     * Insert text at the given index.
+     * Optionally apply formatting to the inserted text.
+     * @param index The index to insert the text at.
+     * @param text The text to insert.
+     * @param attribtues The formatting attributes to apply to the inserted text.
+     */
+    insert(index: number, text: string, attribtues?: Record<string, any>): void;
+    /**
+     * Deletes the given number of items, starting at the given index.
+     * @param index The index of the first item to be deleted.
+     * @param count The number of items to delete.
+     */
+    delete(index: number, count: number): void;
+    /**
+     * Applies the given delta to the text.
+     * @param delta The delta to apply.
+     */
+    applyDelta(delta: SharedTextDelta): void;
+    /**
+     * Converts this text into a delta that can be applied to another text object.
+     */
+    toDelta(): SharedTextDelta;
+    /**
+     * Creates a relative position that is fixed to the code point at the given index.
+     * @param index The index of the character to create the relative position for.
+     * @param assoc The association of the relative position to the character. < 0 is before, >= 0 is after.
+     */
+    encodeRelativePosition(index: number, assoc?: number): RelativePosition;
+    /**
+     * Gets the index that the given relative position is associated with.
+     * @param position The relative position to decode.
+     */
+    decodeRelativePosition(position: RelativePosition): number;
+    /**
+     * Gets a range of text from this object.
+     * Negative indexes can be used to start from the end of the string.
+     * @param start The index of the first code point to retrieve.
+     * @param end The index of the last code point to retrieve.
+     */
+    slice(start?: number, end?: number): string;
+    /**
+     * Creates a new JavaScript string that is a clone of this text.
+     */
+    toString(): string;
+    /**
+     * Transforms this text into a string that can be serialized to JSON.
+     */
+    toJSON(): string;
+    /**
+     * Creates a new shared array that is a clone of this array.
+     */
+    clone(): SharedText;
+    /**
+     * Gets an observable that resolves whenever the array is changed.
+     */
+    readonly changes: Observable<SharedTextChanges>;
+    /**
+     * Gets an observable that resolves whenever this array or any children are changed.
+     */
+    readonly deepChanges: Observable<SharedTextChanges[]>;
+}
+export interface SharedMapChanges<T> {
+    type: 'map';
+    /**
+     * The map that was changed.
+     */
+    target: SharedMap<T>;
+    /**
+     * The keys that were changed, along with their old values.
+     */
+    changes: Map<string, SharedMapChange<T>>;
+}
+export interface SharedMapChange<T> {
+    /**
+     * The action that caused this change.
+     */
+    action: 'add' | 'update' | 'delete';
+    /**
+     * The old value of the key.
+     */
+    oldValue: T | undefined;
+}
+export interface SharedArrayChanges<T> {
+    type: 'array';
+    /**
+     * The array that was changed.
+     */
+    target: SharedArray<T>;
+    /**
+     * The changes that were made to the array.
+     */
+    delta: SharedArrayDelta<T>;
+}
+export type SharedArrayDelta<T> = SharedArrayOp<T>[];
+export type SharedArrayOp<T> = SharedArrayPreserveOp | SharedArrayInsertOp<T> | SharedArrayDeleteOp<T>;
+export interface SharedArrayPreserveOp {
+    type: 'preserve';
+    /**
+     * The number of items that were preserved.
+     */
+    count: number;
+}
+export interface SharedArrayInsertOp<T> {
+    type: 'insert';
+    /**
+     * The values that were inserted.
+     */
+    values: T[];
+}
+export interface SharedArrayDeleteOp<T> {
+    type: 'delete';
+    /**
+     * The number of items that were deleted.
+     */
+    count: number;
+}
+export interface SharedTextChanges {
+    type: 'text';
+    /**
+     * The text that was changed.
+     */
+    target: SharedText;
+    /**
+     * The changes that were made to the array.
+     */
+    delta: SharedTextDelta;
+}
+export type SharedTextDelta = SharedTextOp[];
+export type SharedTextOp = SharedTextPreserveOp | SharedTextInsertOp | SharedTextDeleteOp;
+export interface SharedTextPreserveOp {
+    type: 'preserve';
+    /**
+     * The number of characters that were preserved.
+     */
+    count: number;
+}
+export interface SharedTextInsertOp {
+    type: 'insert';
+    /**
+     * The text that was inserted.
+     */
+    text: string;
+    /**
+     * The formatting that was applied to the inserted text.
+     */
+    attributes: Record<string, any>;
+}
+export interface SharedTextDeleteOp {
+    type: 'delete';
+    /**
+     * The number of items that were deleted.
+     */
+    count: number;
+}
+export interface RelativePosition {
+}
+//# sourceMappingURL=SharedDocument.d.ts.map

package/documents/SharedDocument.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SharedDocument.js.map

package/documents/SharedDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedDocument.js","sourceRoot":"","sources":["SharedDocument.ts"],"names":[],"mappings":""}

package/documents/SharedDocumentConfig.d.ts

@@ -0,0 +1,65 @@
+import { RemoteCausalRepoProtocol } from '../partitions/AuxPartitionConfig';
+/**
+ * Defines a config for a shared document that is stored locally.
+ */
+export interface SharedDocumentConfig {
+    /**
+     * The name of the record that the document is stored under.
+     * If null, then the document will either be stored in a public inst or on the device.
+     */
+    recordName?: string | null;
+    /**
+     * The inst that the document is stored in.
+     * If omitted or null, then the document will only be stored on the device.
+     */
+    inst?: string | null;
+    /**
+     * The branch of the document to load.
+     * If omitted, then local persistence will not be supported.
+     */
+    branch?: string;
+    /**
+     * Whether the doc should be loaded in read-only mode.
+     */
+    readOnly?: boolean;
+    /**
+     * Whether the doc should be loaded without realtime updates and in a read-only mode.
+     * Basically this means that all you get is the initial state.
+     */
+    static?: boolean;
+    /**
+     * Whether the doc should skip the initial load until the doc is upgraded to a realtime connection.
+     */
+    skipInitialLoad?: boolean;
+    /**
+     * Whether the doc should be temporary.
+     */
+    temporary?: boolean;
+    /**
+     * The options for local persistence of the document.
+     * If not provided, then the document will not be persisted locally.
+     */
+    localPersistence?: {
+        /**
+         * Whether to save the document to indexed db.
+         */
+        saveToIndexedDb?: boolean;
+        /**
+         * The key to use for encryption.
+         */
+        encryptionKey?: string;
+    };
+}
+export interface RemoteSharedDocumentConfig extends SharedDocumentConfig {
+    /**
+     * The host to connect to.
+     * If omitted, then connecting to remote servers will not be supported.
+     */
+    host?: string;
+    /**
+     * The protocol to use for the document.
+     * Currently, only "updates" is supported.
+     */
+    connectionProtocol?: RemoteCausalRepoProtocol;
+}
+//# sourceMappingURL=SharedDocumentConfig.d.ts.map

package/documents/SharedDocumentConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SharedDocumentConfig.js.map

package/documents/SharedDocumentConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedDocumentConfig.js","sourceRoot":"","sources":["SharedDocumentConfig.ts"],"names":[],"mappings":""}

package/documents/SharedDocumentFactories.d.ts

@@ -0,0 +1,20 @@
+import { PartitionAuthSource } from '../partitions/PartitionAuthSource';
+import { SharedDocument } from './SharedDocument';
+import { RemoteSharedDocumentConfig } from './SharedDocumentConfig';
+export interface SharedDocumentServices {
+    /**
+     * The auth source that should be used for the partition, if needed.
+     */
+    authSource: PartitionAuthSource;
+}
+export type SharedDocumentFactory = (config: RemoteSharedDocumentConfig, services: SharedDocumentServices) => Promise<SharedDocument> | SharedDocument;
+/**
+ * Creates a shared document from the given list of factory functions.
+ * The first factory function that returns a doc is the document
+ * that gets returned.
+ * @param config The config which indicates the type of document to create.
+ * @param services The services which should be used by the document.
+ * @param factories The factory functions.
+ */
+export declare function createSharedDocument(config: RemoteSharedDocumentConfig, services: SharedDocumentServices, ...factories: SharedDocumentFactory[]): Promise<SharedDocument>;
+//# sourceMappingURL=SharedDocumentFactories.d.ts.map

package/documents/SharedDocumentFactories.js

@@ -0,0 +1,29 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * Creates a shared document from the given list of factory functions.
+ * The first factory function that returns a doc is the document
+ * that gets returned.
+ * @param config The config which indicates the type of document to create.
+ * @param services The services which should be used by the document.
+ * @param factories The factory functions.
+ */
+export function createSharedDocument(config, services, ...factories) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let factory of factories) {
+            let result = yield factory(config, services);
+            if (result) {
+                return result;
+            }
+        }
+        return undefined;
+    });
+}
+//# sourceMappingURL=SharedDocumentFactories.js.map

package/documents/SharedDocumentFactories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SharedDocumentFactories.js","sourceRoot":"","sources":["SharedDocumentFactories.ts"],"names":[],"mappings":";;;;;;;;;AAgBA;;;;;;;GAOG;AACH,MAAM,UAAgB,oBAAoB,CACtC,MAAkC,EAClC,QAAgC,EAChC,GAAG,SAAkC;;QAErC,KAAK,IAAI,OAAO,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7C,IAAI,MAAM,EAAE,CAAC;gBACT,OAAO,MAAM,CAAC;YAClB,CAAC;QACL,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC;CAAA"}