@dittolive/ditto 2.0.8 → 2.1.0

package/types/ditto.d.ts

@@ -679,7 +679,7 @@ declare class MutableRGA extends RGA {
      * @param value - The value to set at the specified index.
      * @param index - The index at which to set the provided value.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     setAt(value: any, index: number): void;
@@ -693,7 +693,7 @@ declare class MutableRGA extends RGA {
      *
      * @param index - The index of the element to remove.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     removeAt(index: number): void;
@@ -707,7 +707,7 @@ declare class MutableRGA extends RGA {
      *
      * @param value - The value to push on to the RGA.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     push(value: any): void;
@@ -721,7 +721,7 @@ declare class MutableRGA extends RGA {
      *
      * @return The value popped off from the end of the RGA.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     pop(): any | null;
@@ -736,7 +736,7 @@ declare class MutableRGA extends RGA {
      * @param value - The value to insert into the RGA.
      * @param index - The index at which to insert the provided value.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     insertAt(value: any, index: number): void;
@@ -815,7 +815,7 @@ declare class DocumentPath {
      * Returns the value at the previously specified key in the document as an
      * {@link RGA} if possible, otherwise returns `null`.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     get rga(): RGA | null;
@@ -879,7 +879,7 @@ declare class MutableDocumentPath {
      * Returns the value at the previously specified key in the document as a
      * {@link MutableRGA} if possible, otherwise returns `null`.
      *
-     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * @deprecated RGA usage should be replaced. Use arrays inside Registers
      * instead.
      */
     get rga(): MutableRGA | null;
@@ -1194,9 +1194,9 @@ declare class UpdateResultsMap {
 
 /**
  * The type that is returned when calling
- * {@link PendingCursorOperation.observe | observe()} on a
+ * {@link PendingCursorOperation.observeLocal | observeLocal()} on a
  * {@link PendingCursorOperation} object. It handles the logic for calling the
- * event handler that is provided to `observe` calls.
+ * event handler that is provided to `observeLocal()` calls.
  *
  * Ditto will prevent the process from exiting as long as there are
  * active live queries (not relevant when running in the browser).
@@ -1377,7 +1377,7 @@ declare type QueryObservationHandler = (documents: Document[], event: LiveQueryE
  * {@link Document | documents} as an immediate return value, or you can
  * establish either a live query or a subscription, which both work over time.
  *
- * A live query, established by calling {@link PendingCursorOperation.observe | observe()}, will notify
+ * A live query, established by calling {@link PendingCursorOperation.observeLocal | observeLocal()}, will notify
  * you every time there's an update to a document that matches the query you
  * provided in the preceding `find`-like call.
  *
@@ -1386,12 +1386,6 @@ declare type QueryObservationHandler = (documents: Document[], event: LiveQueryE
  * like to receive updates from them about documents that match the query you
  * provided in the preceding `find`-like call.
  *
- * Calling {@link PendingCursorOperation.observe | observe()} will generate both a subscription and a
- * live query at the same time.
- *
- * If you'd like to only observe local changes then you can call
- * {@link PendingCursorOperation.observeLocal | observeLocal()}.
- *
  * Update and remove functionality is also exposed through this object.
  */
 declare class PendingCursorOperation implements PromiseLike<Document[]> {
@@ -1461,7 +1455,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      */
     subscribe(): Subscription;
     /**
-     * Enables you to subscribe to changes that occur in a collection locally and
+     * Enables you to listen for changes that occur in a collection locally and
      * remotely.
      *
      * The `handler` block will be called when local or remote changes are
@@ -1477,16 +1471,21 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingCursorOperation.observeLocal | observeLocal()}
+     * and {@link PendingCursorOperation.subscribe | subscribe()} individually
+     * instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
      */
     observe(handler: QueryObservationHandler): LiveQuery;
     /**
-     * Enables you to subscribe to changes that occur in a collection locally and
-     * remotely, and to signal when you are ready for the live query to deliver
+     * Enables you to listen for changes that occur in a collection locally and
+     * remotely and to signal when you are ready for the live query to deliver
      * the next event.
      *
      * The `handler` block will be called when local or remote changes are
      * made to documents that match the query generated by the chain of operations
-     * that precedes the call to {@link PendingCursorOperation.observe | observe()}. The returned
+     * that precedes the call to {@link PendingCursorOperation.observeWithNextSignal | observeWithNextSignal()}. The returned
      * {@link LiveQuery} object must be kept in scope for as long as you want the
      * provided `handler` to be called when an update occurs.
      *
@@ -1497,17 +1496,29 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}
+     * and {@link PendingCursorOperation.subscribe | subscribe()} individually
+     * instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
      */
     observeWithNextSignal(handler: QueryObservationHandler): LiveQuery;
     /**
-     * Enables you to subscribe to changes that occur in a collection locally.
+     * Enables you to listen for changes that occur in a collection locally.
+     *
+     * The `handler` block will be called when local changes are
+     * made to documents that match the query generated by the chain of operations
+     * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}.
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
      *
      * This won't subscribe to receive changes made remotely by others and so it
      * will only fire updates when a local change is made. If you want to receive
-     * remotely performed updates as well then use {@link PendingCursorOperation.observe | observe()} or
-     * call {@link subscribe | subscribe()} with the relevant query. The returned
-     * {@link LiveQuery} object must be kept in scope for as long as you want the
-     * provided `eventHandler` to be called when an update occurs.
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+     * relevant query. The returned {@link LiveQuery} object must be kept in scope
+     * for as long as you want the provided `eventHandler` to be called when an
+     * update occurs.
      *
      * @param handler A closure that will be called every time there is a
      * transaction committed to the store that involves modifications to documents
@@ -1518,14 +1529,22 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      */
     observeLocal(handler: QueryObservationHandler): LiveQuery;
     /**
-     * Enables you to subscribe to changes that occur in a collection locally and
+     * Enables you to listen for changes that occur in a collection locally and
      * to signal when you are ready for the live query to deliver the next event.
      *
-     * The `handler` block will be called when local or remote changes are
+     * The `handler` block will be called when local changes are
      * made to documents that match the query generated by the chain of operations
-     * that precedes the call to {@link PendingCursorOperation.observe | observe()}. The returned
-     * {@link LiveQuery} object must be kept in scope for as long as you want the
-     * provided `handler` to be called when an update occurs.
+     * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}.
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
+     *
+     * This won't subscribe to receive changes made remotely by others and so it
+     * will only fire updates when a local change is made. If you want to receive
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+     * relevant query. The returned {@link LiveQuery} object must be kept in scope
+     * for as long as you want the provided `eventHandler` to be called when an
+     * update occurs.
      *
      * @param handler A closure that will be called every time there is a
      * transaction committed to the store that involves modifications to
@@ -1576,12 +1595,13 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
     /** @internal */
     constructor(query: string, queryArgs: QueryArguments | null, collection: Collection);
     /** @internal */
+    _observe(handler: QueryObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
+    /** @internal */
     then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
     private queryArgsCBOR;
     private currentLimit;
     private currentOffset;
     private orderBys;
-    private _observe;
 }
 
 /**
@@ -1597,7 +1617,7 @@ declare type SingleObservationHandler = (document: Document | null, event: Singl
  * return value, or you can establish either a live query or a subscription,
  * which both work over time.
  *
- * A live query, established by calling {@link PendingIDSpecificOperation.observe | observe()}, will notify
+ * A live query, established by calling {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, will notify
  * you every time there's an update to the document with the ID you provided in
  * the preceding {@link Collection.findByID | findByID()} call.
  *
@@ -1606,12 +1626,6 @@ declare type SingleObservationHandler = (document: Document | null, event: Singl
  * them about the document with the ID you provided in the preceding
  * {@link Collection.findByID | findByID()} call.
  *
- * Calling {@link PendingIDSpecificOperation.observe | observe()} will generate both a subscription and a
- * live query at the same time.
- *
- * If you'd like to only observe local changes then you can call
- * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}.
- *
  * Update and remove functionality is also exposed through this object.
  */
 declare class PendingIDSpecificOperation implements PromiseLike<Document | undefined> {
@@ -1652,6 +1666,11 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingIDSpecificOperation.observeLocal | observeLocal()}
+     * and {@link PendingIDSpecificOperation.subscribe | subscribe()} individually
+     * instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
      */
     observe(handler: SingleObservationHandler): LiveQuery;
     /**
@@ -1661,7 +1680,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      *
      * The `handler` closure will be called when local or remote changes are
      * made to the document referenced by the {@link Collection.findByID | findByID()} call
-     * that precedes the call to {@link PendingIDSpecificOperation.observe | observe()}.
+     * that precedes the call to {@link PendingIDSpecificOperation.observeWithNextSignal | observeWithNextSignal()}.
      *
      * The returned {@link LiveQuery} object must be kept in scope for as long as
      * you want the provided `handler` to be called when an update occurs.
@@ -1669,10 +1688,15 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * @param handler A closure that will be called every time there is a
      * transaction committed to the store that involves a modification to the
      * document with the relevant ID in the collection that
-     * {@link PendingIDSpecificOperation.observe | observe()} was called on.
+     * {@link PendingIDSpecificOperation.observeWithNextSignal | observeWithNextSignal()} was called on.
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingIDSpecificOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}
+     * and {@link PendingIDSpecificOperation.subscribe | subscribe()} individually
+     * instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
      */
     observeWithNextSignal(handler: SingleObservationHandler): LiveQuery;
     /**
@@ -1681,9 +1705,9 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      *
      * This won't subscribe to receive changes made remotely by others and so it
      * will only fire updates when a local change is made. If you want to receive
-     * remotely performed updates as well then use {@link PendingIDSpecificOperation.observe | observe()} or
-     * also call {@link subscribe | subscribe()} separately, using another
-     * {@link Collection.findByID | findByID()} call that references the same document ID.
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+     * document ID.
      *
      * The returned {@link LiveQuery} object must be kept in scope for as long
      * as you want the provided `handler` to be called when an update
@@ -1700,14 +1724,14 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
     observeLocal(handler: SingleObservationHandler): LiveQuery;
     /**
      * Enables you to listen for changes that occur in relation to a document
-     * locally  and to signal when you are ready for the live query to deliver
+     * locally and to signal when you are ready for the live query to deliver
      * the next event.
      *
      * This won't subscribe to receive changes made remotely by others and so it
      * will only fire updates when a local change is made. If you want to receive
-     * remotely performed updates as well then use {@link PendingIDSpecificOperation.observe | observe()} or
-     * also call {@link subscribe | subscribe()} separately, using another
-     * {@link Collection.findByID | findByID()} call that references the same document ID.
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+     * document ID.
      *
      * The returned {@link LiveQuery} object must be kept in scope for as long
      * as you want the provided `handler` to be called when an update
@@ -1759,10 +1783,11 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
     /** @internal */
     constructor(documentID: DocumentID, collection: Collection);
     /** @internal */
+    _observe(handler: SingleObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
+    /** @internal */
     then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
     private documentIDCBOR;
     private get query();
-    private _observe;
 }
 
 declare type UpsertOptions = {
@@ -1785,9 +1810,9 @@ declare class Collection {
      * Generates a {@link PendingCursorOperation} using the provided query.
      *
      * The returned object can be used to find and return the documents or you can
-     * chain a call to `observe` or `subscribe` if you want to get updates about
-     * the list of matching documents over time. It can also be used to update,
-     * remove or evict the matching documents.
+     * chain a call to `observeLocal()` or `subscribe()` if you want to get updates
+     * about the list of matching documents over time. It can also be used to
+     * update, remove or evict the matching documents.
      *
      * You can incorporate dynamic data into the query string with placeholders
      * in the form of `$args.my_arg_name`, along with providing an accompanying
@@ -1811,7 +1836,7 @@ declare class Collection {
      * ID.
      *
      * The returned object can be used to find and return the document or you can
-     * chain a call to {@link PendingIDSpecificOperation.observe | observe()}, or {@link PendingIDSpecificOperation.subscribe | subscribe()}
+     * chain a call to {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, or {@link PendingIDSpecificOperation.subscribe | subscribe()}
      * if you want to get updates about the document over time. It can also be
      * used to update, remove or evict the document.
      *
@@ -1955,7 +1980,7 @@ declare class CollectionsEvent {
  * The closure that is called whenever the collections covered by a live query
  * change.
  */
-declare type CollectionsObservationHandler = (event: CollectionsEvent) => void | Promise<void>;
+declare type CollectionsObservationHandler = (event: CollectionsEvent, signalNext?: () => void) => void | Promise<void>;
 /**
  * These objects are returned when calling {@link Store.collections | collections()}
  * on {@link Store}.
@@ -1965,16 +1990,13 @@ declare type CollectionsObservationHandler = (event: CollectionsEvent) => void |
  * {@link Collection}s as an immediate return value, or you can establish either
  * a live query or a subscription, which both work over time.
  *
- * A live query, established by calling {@link PendingCollectionsOperation.observe | observe()}, will notify
+ * A live query, established by calling {@link PendingCollectionsOperation.observeLocal | observeLocal()}, will notify
  * you every time there's a change in the collections that the device knows
  * about.
  *
  * A subscription, established by calling {@link subscribe | subscribe()}, will
  * act as a signal to other peers that the device connects to that you would
  * like to receive updates from them about the collections that they know about.
- *
- * Calling {@link PendingCollectionsOperation.observe | observe()} will generate both a subscription and a
- * live query at the same time.
  */
 declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
     /**
@@ -2039,8 +2061,72 @@ declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingCollectionsOperation.observeLocal | observeLocal()}
+     * and {@link PendingCollectionsOperation.subscribe | subscribe()}
+     * individually instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
      */
     observe(handler: CollectionsObservationHandler): LiveQuery;
+    /**
+     * Enables you to listen for changes that occur in relation to the collections
+     * that are known about. A block gets called when an update is received either
+     * locally or remotely. You can signal when you are ready for the next event
+     * to be delivered.
+     *
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
+     *
+     * @param handler A closure that will be called every time there is an update
+     * about the list of known about collections.
+     *
+     * @return A {@link LiveQuery} object that must be kept in scope for as long
+     * as you want to keep receiving updates.
+     *
+     * @deprecated Use {@link PendingCollectionsOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}
+     * and {@link PendingCollectionsOperation.subscribe | subscribe()}
+     * individually instead. For more info, please consult the
+     * {@link https://docs.ditto.live/javascript/common/concepts/syncing-data | corresponding Ditto docs}.
+     */
+    observeWithNextSignal(handler: CollectionsObservationHandler): LiveQuery;
+    /**
+     * Enables you to listen for changes that occur in relation to the collections
+     * that are known about locally.
+     *
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
+     *
+     * This won't subscribe to receive updates from other devices and so it will
+     * only fire when a local change to the known about collections occurs. If
+     * you want to receive remote updates as well, then create a subscription via
+     * {@link PendingCollectionsOperation.subscribe | subscribe()}.
+     *
+     * @param handler A closure that will be called every time there is an update
+     * about the list of known about collections.
+     *
+     * @return A {@link LiveQuery} object that must be kept in scope for as long
+     * as you want to keep receiving updates.
+     */
+    observeLocal(handler: CollectionsObservationHandler): LiveQuery;
+    /**
+     * Enables you to listen for changes that occur in relation to the collections
+     * that are known about locally.
+     *
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
+     *
+     * This won't subscribe to receive updates from other devices and so it will
+     * only fire when a local change to the known about collections occurs. If
+     * you want to receive remote updates as well, then create a subscription via
+     * {@link PendingCollectionsOperation.subscribe | subscribe()}.
+     *
+     * @param handler A closure that will be called every time there is an update
+     * about the list of known about collections.
+     *
+     * @return A {@link LiveQuery} object that must be kept in scope for as long
+     * as you want to keep receiving updates.
+     */
+    observeLocalWithNextSignal(handler: CollectionsObservationHandler): LiveQuery;
     /**
      * Return the list of collections requested based on the preceding function
      * chaining.
@@ -2055,7 +2141,8 @@ declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
     constructor(store: Store);
     /** @internal */
     then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
-    /** @private */
+    /** @internal */
+    _observe(handler: CollectionsObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
     private readonly pendingCursorOperation;
 }