breeze-client 2.2.2 → 3.0.0

package/rxjs/breeze-rxjs.js

@@ -0,0 +1,117 @@
+import { Observable } from 'rxjs';
+// Breeze events as RxJS observables.
+//
+// Optional, and opt-in: import it from its own subpath, and install `rxjs` yourself.
+//
+//     import { entityChanged$, hasChanges$ } from 'breeze-client/rxjs';
+//
+// Nothing in `breeze-client` itself imports this module or rxjs, so an application that does not
+// use it pays nothing - not a byte of bundle and not a transitive install. `rxjs` is an optional
+// peer dependency for that reason: a plain peer dependency would be installed automatically by
+// npm 7 and later, for everyone.
+//
+// Every observable here is cold and lazy. Creating one does nothing; subscribing to it subscribes
+// to the Breeze event, and unsubscribing - directly, or through an operator such as `take`,
+// `takeUntil` or Angular's `async` pipe - removes that subscription again. That matters: a Breeze
+// event holds its subscribers, so a subscription that is never removed keeps its callback, and
+// everything the callback reaches, for as long as the event's owner lives.
+//
+// Only the `Observable` constructor is used, no operators, so any rxjs from 7.0 on will do.
+/**
+ * Any {@link BreezeEvent} as an Observable: each value the event publishes is emitted, for as long
+ * as the subscription lasts.
+ *
+ * The other functions in this module are this, applied to a particular event. Use it directly for
+ * the ones they do not cover - `metadataStore.metadataFetched`, say.
+ *
+ * ```ts
+ * fromBreezeEvent(em.metadataStore.metadataFetched).subscribe(args => console.log(args.metadata));
+ * ```
+ *
+ * An error thrown by a subscriber does not reach Breeze: rxjs reports it on its own, and the
+ * event's other subscribers still hear about the change.
+ *
+ * @param event - the event to observe
+ * @returns an Observable that subscribes to `event` when it is subscribed to, and unsubscribes when
+ * it is torn down
+ */
+export function fromBreezeEvent(event) {
+    return new Observable(subscriber => {
+        const unsubKey = event.subscribe(data => subscriber.next(data));
+        return () => { event.unsubscribe(unsubKey); };
+    });
+}
+/**
+ * {@link EntityManager.entityChanged} as an Observable: every entity added, attached, detached,
+ * changed, saved or rejected in `em`.
+ *
+ * Filter for what you want with rxjs:
+ *
+ * ```ts
+ * entityChanged$(em).pipe(
+ *   filter(e => e.entityAction === EntityAction.PropertyChange),
+ * ).subscribe(e => markDirty(e.entity));
+ * ```
+ */
+export function entityChanged$(em) {
+    return fromBreezeEvent(em.entityChanged);
+}
+/**
+ * Whether `em` has unsaved changes, as an Observable that starts with the current value.
+ *
+ * {@link EntityManager.hasChangesChanged} only fires on a change, so on its own it cannot tell a
+ * late subscriber what the answer is *now*. This emits `em.hasChanges()` as soon as it is
+ * subscribed to, then each change after that, and never the same value twice in a row. Bind a Save
+ * button to it and the button is right from the first render.
+ *
+ * ```ts
+ * hasChanges$(em).subscribe(dirty => saveButton.disabled = !dirty);
+ * ```
+ *
+ * The current value is read when you subscribe, not when you call this function.
+ */
+export function hasChanges$(em) {
+    return new Observable(subscriber => {
+        let last = em.hasChanges();
+        // Subscribe to Breeze before emitting the current value. A subscriber that reacts to that
+        // first value by changing the manager - creating an entity, say - then has the change reported
+        // to it rather than lost in the gap between reading the value and listening for the next one.
+        const unsubKey = em.hasChangesChanged.subscribe(args => {
+            if (args.hasChanges !== last) {
+                last = args.hasChanges;
+                subscriber.next(last);
+            }
+        });
+        subscriber.next(last);
+        // If the subscriber took only the first value, it has already unsubscribed by now, before this
+        // teardown was handed back. rxjs runs a teardown returned to a closed subscriber at once, so
+        // the Breeze subscription is still removed.
+        return () => { em.hasChangesChanged.unsubscribe(unsubKey); };
+    });
+}
+/**
+ * {@link EntityManager.validationErrorsChanged} as an Observable: validation errors added to or
+ * removed from any entity in `em`.
+ *
+ * Each value says what changed, not the complete set. For "every validation error in the manager
+ * right now", see the recipe in the guide, which builds one from this.
+ */
+export function validationErrorsChanged$(em) {
+    return fromBreezeEvent(em.validationErrorsChanged);
+}
+/**
+ * {@link EntityAspect.propertyChanged} as an Observable: each property of one entity that changes.
+ *
+ * ```ts
+ * propertyChanged$(order).pipe(
+ *   filter(e => e.propertyName === 'shipCountry'),
+ * ).subscribe(() => recalculateTax(order));
+ * ```
+ *
+ * A live subscription keeps `entity` reachable, as any subscription to it would. Unsubscribe when
+ * the screen showing it goes away.
+ */
+export function propertyChanged$(entity) {
+    return fromBreezeEvent(entity.entityAspect.propertyChanged);
+}
+//# sourceMappingURL=breeze-rxjs.js.map

package/rxjs/breeze-rxjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breeze-rxjs.js","sourceRoot":"","sources":["../../src/rxjs/breeze-rxjs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAOlC,qCAAqC;AACrC,EAAE;AACF,qFAAqF;AACrF,EAAE;AACF,wEAAwE;AACxE,EAAE;AACF,iGAAiG;AACjG,iGAAiG;AACjG,+FAA+F;AAC/F,iCAAiC;AACjC,EAAE;AACF,kGAAkG;AAClG,4FAA4F;AAC5F,kGAAkG;AAClG,+FAA+F;AAC/F,2EAA2E;AAC3E,EAAE;AACF,4FAA4F;AAE5F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAI,KAAqB;IACtD,OAAO,IAAI,UAAU,CAAI,UAAU,CAAC,EAAE;QACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAChE,OAAO,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,EAAiB;IAC9C,OAAO,eAAe,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,EAAiB;IAC3C,OAAO,IAAI,UAAU,CAAU,UAAU,CAAC,EAAE;QAC1C,IAAI,IAAI,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC;QAC3B,0FAA0F;QAC1F,+FAA+F;QAC/F,8FAA8F;QAC9F,MAAM,QAAQ,GAAG,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;YACrD,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;gBAC7B,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC;gBACvB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;QACH,CAAC,CAAC,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,+FAA+F;QAC/F,6FAA6F;QAC7F,4CAA4C;QAC5C,OAAO,GAAG,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,EAAiB;IACxD,OAAO,eAAe,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,eAAe,CAAC,MAAM,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["import { Observable } from 'rxjs';\nimport type { BreezeEvent } from '../core/event.js';\nimport type { Entity, PropertyChangedEventArgs } from '../entity/entity-aspect.js';\nimport type {\n  EntityChangedEventArgs, EntityManager, ValidationErrorsChangedEventArgs,\n} from '../manager/entity-manager.js';\n\n// Breeze events as RxJS observables.\n//\n// Optional, and opt-in: import it from its own subpath, and install `rxjs` yourself.\n//\n//     import { entityChanged$, hasChanges$ } from 'breeze-client/rxjs';\n//\n// Nothing in `breeze-client` itself imports this module or rxjs, so an application that does not\n// use it pays nothing - not a byte of bundle and not a transitive install. `rxjs` is an optional\n// peer dependency for that reason: a plain peer dependency would be installed automatically by\n// npm 7 and later, for everyone.\n//\n// Every observable here is cold and lazy. Creating one does nothing; subscribing to it subscribes\n// to the Breeze event, and unsubscribing - directly, or through an operator such as `take`,\n// `takeUntil` or Angular's `async` pipe - removes that subscription again. That matters: a Breeze\n// event holds its subscribers, so a subscription that is never removed keeps its callback, and\n// everything the callback reaches, for as long as the event's owner lives.\n//\n// Only the `Observable` constructor is used, no operators, so any rxjs from 7.0 on will do.\n\n/**\n * Any {@link BreezeEvent} as an Observable: each value the event publishes is emitted, for as long\n * as the subscription lasts.\n *\n * The other functions in this module are this, applied to a particular event. Use it directly for\n * the ones they do not cover - `metadataStore.metadataFetched`, say.\n *\n * ```ts\n * fromBreezeEvent(em.metadataStore.metadataFetched).subscribe(args => console.log(args.metadata));\n * ```\n *\n * An error thrown by a subscriber does not reach Breeze: rxjs reports it on its own, and the\n * event's other subscribers still hear about the change.\n *\n * @param event - the event to observe\n * @returns an Observable that subscribes to `event` when it is subscribed to, and unsubscribes when\n * it is torn down\n */\nexport function fromBreezeEvent<T>(event: BreezeEvent<T>): Observable<T> {\n  return new Observable<T>(subscriber => {\n    const unsubKey = event.subscribe(data => subscriber.next(data));\n    return () => { event.unsubscribe(unsubKey); };\n  });\n}\n\n/**\n * {@link EntityManager.entityChanged} as an Observable: every entity added, attached, detached,\n * changed, saved or rejected in `em`.\n *\n * Filter for what you want with rxjs:\n *\n * ```ts\n * entityChanged$(em).pipe(\n *   filter(e => e.entityAction === EntityAction.PropertyChange),\n * ).subscribe(e => markDirty(e.entity));\n * ```\n */\nexport function entityChanged$(em: EntityManager): Observable<EntityChangedEventArgs> {\n  return fromBreezeEvent(em.entityChanged);\n}\n\n/**\n * Whether `em` has unsaved changes, as an Observable that starts with the current value.\n *\n * {@link EntityManager.hasChangesChanged} only fires on a change, so on its own it cannot tell a\n * late subscriber what the answer is *now*. This emits `em.hasChanges()` as soon as it is\n * subscribed to, then each change after that, and never the same value twice in a row. Bind a Save\n * button to it and the button is right from the first render.\n *\n * ```ts\n * hasChanges$(em).subscribe(dirty => saveButton.disabled = !dirty);\n * ```\n *\n * The current value is read when you subscribe, not when you call this function.\n */\nexport function hasChanges$(em: EntityManager): Observable<boolean> {\n  return new Observable<boolean>(subscriber => {\n    let last = em.hasChanges();\n    // Subscribe to Breeze before emitting the current value. A subscriber that reacts to that\n    // first value by changing the manager - creating an entity, say - then has the change reported\n    // to it rather than lost in the gap between reading the value and listening for the next one.\n    const unsubKey = em.hasChangesChanged.subscribe(args => {\n      if (args.hasChanges !== last) {\n        last = args.hasChanges;\n        subscriber.next(last);\n      }\n    });\n    subscriber.next(last);\n    // If the subscriber took only the first value, it has already unsubscribed by now, before this\n    // teardown was handed back. rxjs runs a teardown returned to a closed subscriber at once, so\n    // the Breeze subscription is still removed.\n    return () => { em.hasChangesChanged.unsubscribe(unsubKey); };\n  });\n}\n\n/**\n * {@link EntityManager.validationErrorsChanged} as an Observable: validation errors added to or\n * removed from any entity in `em`.\n *\n * Each value says what changed, not the complete set. For \"every validation error in the manager\n * right now\", see the recipe in the guide, which builds one from this.\n */\nexport function validationErrorsChanged$(em: EntityManager): Observable<ValidationErrorsChangedEventArgs> {\n  return fromBreezeEvent(em.validationErrorsChanged);\n}\n\n/**\n * {@link EntityAspect.propertyChanged} as an Observable: each property of one entity that changes.\n *\n * ```ts\n * propertyChanged$(order).pipe(\n *   filter(e => e.propertyName === 'shipCountry'),\n * ).subscribe(() => recalculateTax(order));\n * ```\n *\n * A live subscription keeps `entity` reachable, as any subscription to it would. Unsubscribe when\n * the screen showing it goes away.\n */\nexport function propertyChanged$(entity: Entity): Observable<PropertyChangedEventArgs> {\n  return fromBreezeEvent(entity.entityAspect.propertyChanged);\n}\n"]}