@dereekb/dbx-core 13.0.4 → 13.0.6

package/fesm2022/dereekb-dbx-core.mjs

@@ -19,6 +19,15 @@ import { formatDate } from '@angular/common';
  * when the DestroyRef is destroyed in the context.
  *
  * Must be run in an Angular injection context.
+ *
+ * @example
+ * // Clean up a Destroyable object (e.g., SubscriptionObject, LockSet):
+ * const sub = new SubscriptionObject(obs$.subscribe(handler));
+ * clean(sub);
+ *
+ * @example
+ * // Clean up a destroy function directly:
+ * clean(() => resource.release());
  */
 function clean(input) {
     const destroyRef = inject(DestroyRef);
@@ -35,6 +44,14 @@ function clean(input) {
  * when the DestroyRef is destroyed in the context.
  *
  * Must be run in an Angular injection context.
+ *
+ * @example
+ * // Complete a BehaviorSubject when the component is destroyed:
+ * readonly value$ = completeOnDestroy(new BehaviorSubject<string>('initial'));
+ *
+ * @example
+ * // Complete a ReplaySubject when the component is destroyed:
+ * readonly events$ = completeOnDestroy(new ReplaySubject<Event>(1));
  */
 function completeOnDestroy(input) {
     clean(() => input.complete());
@@ -46,6 +63,14 @@ function completeOnDestroy(input) {
  * Creates a new SubscriptionObject that is automatically destroyed when the context is destroyed.
  *
  * Must be run within an Angular injection context.
+ *
+ * @example
+ * // Pass a subscription directly - it will be cleaned up automatically:
+ * cleanSubscription(obs$.subscribe(handler));
+ *
+ * // Or create first, then set the subscription later:
+ * readonly _sub = cleanSubscription();
+ * this._sub.subscription = obs$.subscribe(handler);
  */
 function cleanSubscription(sub) {
     const subscription = getValueFromGetter(sub);
@@ -59,7 +84,17 @@ function cleanSubscription(sub) {
  *
  * Must be run within an Angular injection context.
  *
- * @param onLockSetDestroy Optional callback to run when the lockset is unlocked.
+ * @param config Optional configuration for destruction behavior and callbacks.
+ *
+ * @example
+ * // Create a simple lockset:
+ * readonly lockSet = cleanLockSet();
+ *
+ * @example
+ * // Create with a callback when the lockset is destroyed:
+ * readonly lockSet = cleanLockSet({
+ *   onLockSetDestroy: () => console.log('lockset destroyed')
+ * });
  */
 function cleanLockSet(config) {
     const { onDestroy, onLockSetDestroy, destroyLocksetTiming } = config ?? {};
@@ -87,6 +122,10 @@ function cleanLockSet(config) {
  *
  * @param lockSet The lockset to use.
  * @param onDestroy The function to run when the lockset is unlocked.
+ *
+ * @example
+ * // Defer cleanup until the lockset unlocks after component destroy:
+ * cleanWithLockSet(this.lockSet, () => resource.release());
  */
 function cleanWithLockSet(lockSet, onDestroy) {
     const destroyRef = inject(DestroyRef);
@@ -100,6 +139,18 @@ function cleanWithLockSet(lockSet, onDestroy) {
  * Creates a new SubscriptionObject that is automatically destroyed when the context is destroyed, and the lock set's next unlock occurs.
  *
  * Must be run within an Angular injection context.
+ *
+ * @example
+ * // Pass a subscription that waits for the lockset to unlock before cleanup:
+ * readonly _sub = cleanSubscriptionWithLockSet({
+ *   lockSet: this.lockSet,
+ *   sub: obs$.subscribe(handler)
+ * });
+ *
+ * @example
+ * // Create first, then set the subscription later:
+ * readonly _sub = cleanSubscriptionWithLockSet({ lockSet: this.lockSet });
+ * this._sub.subscription = obs$.subscribe(handler);
  */
 function cleanSubscriptionWithLockSet(input) {
     const subscription = getValueFromGetter(input.sub);
@@ -112,6 +163,15 @@ function cleanSubscriptionWithLockSet(input) {
  * Creates a new LoadingStateContext that is automatically destroyed when the context is destroyed.
  *
  * Must be run within an Angular injection context.
+ *
+ * @example
+ * // Create with an observable source:
+ * readonly context = cleanLoadingContext<MyData>(this.data$);
+ *
+ * @example
+ * // Create empty, then set the observable source later:
+ * readonly context = cleanLoadingContext<MyData>();
+ * this.context.obs = this.data$;
  */
 function cleanLoadingContext(input) {
     return clean(loadingStateContext(input));
@@ -120,6 +180,15 @@ function cleanLoadingContext(input) {
  * Creates a new ListLoadingStateContext that is automatically destroyed when the context is destroyed.
  *
  * Must be run within an Angular injection context.
+ *
+ * @example
+ * // Create with an observable source:
+ * readonly listContext = cleanListLoadingContext<MyItem>(this.items$);
+ *
+ * @example
+ * // Create empty, then set the observable source later:
+ * readonly listContext = cleanListLoadingContext<MyItem>();
+ * this.listContext.obs = this.items$;
  */
 function cleanListLoadingContext(input) {
     return clean(listLoadingStateContext(input));
@@ -129,6 +198,15 @@ function cleanListLoadingContext(input) {
  * Creates a new DestroyFunctionObject that is automatically destroyed when the context is destroyed.
  *
  * Must be run within an Angular injection context.
+ *
+ * @example
+ * // Pass a destroy function directly:
+ * cleanDestroy(() => resource.release());
+ *
+ * @example
+ * // Create first, then set the destroy function later:
+ * readonly _destroy = cleanDestroy();
+ * this._destroy.setDestroyFunction(() => resource.release());
  */
 function cleanDestroy(input) {
     const destroyFunction = new DestroyFunctionObject(input);