@emuanalytics/flow-rdf-core 4.0.3 → 4.0.5

package/dist/lib/state-store/decorators.mjs

@@ -0,0 +1,83 @@
+import * as mobx from 'mobx';
+import { toJS } from 'mobx';
+import { createDecoratorAnnotation, createDecoratorAnnotationWithArg } from '../utils/decorators.mjs';
+
+const SYNC_ANNOTATION_TYPE = "state-sync-annotation";
+const REACTIVE_ANNOTATION_TYPE = "state-reactive-annotation";
+const serializeRaw = {
+  annotationType: SYNC_ANNOTATION_TYPE,
+  type: "raw",
+  serialize(val) {
+    return toJS(val);
+  },
+  deserialize(val) {
+    return val;
+  }
+};
+const serializeString = {
+  annotationType: SYNC_ANNOTATION_TYPE,
+  type: "string",
+  serialize(val) {
+    return val.toString();
+  },
+  deserialize(val) {
+    return val;
+  }
+};
+const serializeNumber = {
+  annotationType: SYNC_ANNOTATION_TYPE,
+  type: "number",
+  serialize(val) {
+    return val.toString();
+  },
+  deserialize(val) {
+    return +val;
+  }
+};
+const serializeJson = {
+  annotationType: SYNC_ANNOTATION_TYPE,
+  type: "json",
+  serialize(val) {
+    return JSON.stringify(val);
+  },
+  deserialize(val) {
+    return JSON.parse(val);
+  }
+};
+const serializeState = {
+  annotationType: SYNC_ANNOTATION_TYPE,
+  type: "state",
+  serialize(val, group) {
+    return val.serialize("raw", group);
+  },
+  deserialize(val, target) {
+    target.deserialize("raw", val);
+    return target;
+  }
+};
+const serialize = Object.assign(createDecoratorAnnotation(serializeRaw), {
+  raw: createDecoratorAnnotation(serializeRaw),
+  string: createDecoratorAnnotation(serializeString),
+  number: createDecoratorAnnotation(serializeNumber),
+  json: createDecoratorAnnotation(serializeJson),
+  state: createDecoratorAnnotation(serializeState),
+  for: createDecoratorAnnotationWithArg(serializeRaw)
+});
+function createReactiveAnnotation(mobxAnnotation) {
+  return createDecoratorAnnotation({
+    annotationType: REACTIVE_ANNOTATION_TYPE,
+    mobxAnnotation
+  });
+}
+const observable = Object.assign(createReactiveAnnotation(mobx.observable), {
+  deep: createReactiveAnnotation(mobx.observable.deep),
+  ref: createReactiveAnnotation(mobx.observable.ref),
+  struct: createReactiveAnnotation(mobx.observable.struct),
+  shallow: createReactiveAnnotation(mobx.observable.shallow)
+});
+const computed = Object.assign(createReactiveAnnotation(mobx.computed), {
+  struct: createReactiveAnnotation(mobx.computed.struct)
+});
+const action = createReactiveAnnotation(mobx.action);
+
+export { REACTIVE_ANNOTATION_TYPE, SYNC_ANNOTATION_TYPE, action, computed, observable, serialize };

package/dist/lib/state-store/state-store.mjs

@@ -0,0 +1,534 @@
+import Debug from 'debug';
+import lzString from 'lz-string';
+import * as mobx from 'mobx';
+import { toStream } from 'mobx-utils';
+import { collectStoredAnnotations } from '../utils/decorators.mjs';
+import { randomId } from '../utils/random-id.mjs';
+import { REACTIVE_ANNOTATION_TYPE, SYNC_ANNOTATION_TYPE } from './decorators.mjs';
+import { ensureArray } from '../utils/ensure-array.mjs';
+import { isDefined } from '../utils/type-checks.mjs';
+import { FlowCoreError } from '../errors/flow-error.mjs';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const debug = Debug("flow:state-store");
+const StateStoreMarker = Symbol("FlowCoreStateStoreMarker");
+const StateStorCache = Symbol("FlowCoreStateStorCache");
+class StateStore {
+  /**
+   * Constructs a new `StateStore`.
+   *
+   * In derived classes, call `super()` in the constructor followed by `this.initialize(...)`.
+   *
+   * @example
+   * ```js
+   * constructor() {
+   *   super();
+   *
+   *   // Required!
+   *   this.initialize();
+   * }
+   * ```
+   * @param id - Optional unique identifier for debugging purposes. If not supplied, a random identifier will be generated.
+   */
+  constructor(id) {
+    __publicField(this, "serializationAnnotations", {});
+    __publicField(this, "id");
+    this.id = id || randomId("state");
+  }
+  get formattedName() {
+    return `StateStore<${this.id}>`;
+  }
+  /**
+   * Returns `true` if the store has been initialized.
+   *
+   * Derived state stores **must** be initialized before use by calling {@link StateStore.initialize}
+   * in the constructor.
+   *
+   * @returns `true` if the store has been initialized.
+   */
+  get initialized() {
+    return mobx.isObservable(this);
+  }
+  /**
+   * Returns the value at the specified path in the state store.
+   *
+   * @param path - State store path to retrieve.
+   * @typeParam TPath - Type defining possible state store paths.
+   * @returns The value of the state store property at the specified path.
+   */
+  get(path) {
+    this.checkInitialized();
+    const pathStr = path;
+    let value = this;
+    const p = pathStr.split(".");
+    let k;
+    while (k = p.shift()) {
+      value = value[k];
+    }
+    return value;
+  }
+  /**
+   * Sets the value at the specified path in the state store.
+   *
+   * @param path - State store path to set
+   * @param val - Value to set at the specified path
+   */
+  set(path, val) {
+    this.checkInitialized();
+    const pathArray = path.split(".");
+    let k;
+    let value = this;
+    while (pathArray.length > 1) {
+      k = pathArray.shift();
+      value = value[k];
+    }
+    k = pathArray.shift();
+    value[k] = val;
+  }
+  /**
+   * Use this method to batch multiple state updates into a single transaction.
+   * This can improve performance by reducing the number of reactive updates triggered by
+   * state updates.
+   *
+   * @example
+   * Set multiple state properties within a transaction:
+   * ```js
+   * store.transaction(() => {
+   *  store.set('a', 1);
+   *  store.set('b', 2);
+   *  store.set('c', 3);
+   * });
+   * ```
+   *
+   * @param fn - The function to run within the transaction.
+   */
+  transaction(fn) {
+    this.checkInitialized();
+    mobx.runInAction(() => fn(this));
+  }
+  /**
+   * Toggles the value at the specified path in the state store.
+   * This method assumes that the value at the specified path is a boolean.
+   *
+   * @param path - The path to the boolean value to toggle.
+   * @returns The new value at the specified path.
+   */
+  toggle(path) {
+    this.checkInitialized();
+    const val = !this.get(path);
+    this.set(path, val);
+    return val;
+  }
+  /**
+   * Increments the value at the specified path in the state store.
+   * This method assumes that the value at the specified path is a number.
+   *
+   * @param path - The path to the number value to increment.
+   * @returns The new value at the specified path.
+   */
+  increment(path) {
+    this.checkInitialized();
+    const val = +this.get(path) + 1;
+    this.set(path, val);
+    return val;
+  }
+  /**
+   * Decrements the value at the specified path in the state store.
+   * This method assumes that the value at the specified path is a number.
+   *
+   * @param path The path to the number value to decrement.
+   * @returns The new value at the specified path.
+   */
+  decrement(path) {
+    this.checkInitialized();
+    const val = +this.get(path) - 1;
+    this.set(path, val);
+    return val;
+  }
+  /**
+   * Bind an HTML control element to a state store property. Two-way binding
+   * is established between the control and the state store property. When the
+   * control value changes, the state store property is updated. When the state
+   * store property changes, the control value is updated.
+   *
+   * Supports:
+   * - Native elements that emit an `input` event and have a `value` property.
+   * - Flo.w RDF UI custom elements that emit `flow-ui-input` or `flow-ui-change` events and have
+   * a value property.
+   *
+   * :::warning
+   * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+   * :::
+   *
+   * :::warning
+   * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+   * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+   * :::
+   *
+   * @example
+   * ```js
+   * const subscription = store.bindControl(document.getElementById('my-input'), 'myStateProperty');
+   * ...
+   * subscription.unsubscribe();
+   * ```
+   *
+   * @param el - The HTML element to bind
+   * @param statePath - The path to the state store property to bind
+   * @param options - Binding options
+   * @param options.toState - A function to convert the control value to the state store value
+   * @param options.fromState - A function to convert the state store value to the control value
+   * @param options.updateOn - The event type that will trigger an update of the state store property. Default is `input`.
+   * @returns A subscription that can be used to `unsubscribe()` the binding.
+   */
+  bindControl(el, statePath, options) {
+    const toState = options?.toState ?? ((v) => v);
+    const fromState = options?.fromState ?? ((v) => v);
+    const updateOn = options?.updateOn ?? "input";
+    el.addEventListener("input", () => {
+      if (updateOn === "input") {
+        this.set(statePath, toState(el.value));
+      }
+    });
+    el.addEventListener("flow-ui-input", () => {
+      if (updateOn === "input") {
+        this.set(statePath, toState(el.value));
+      }
+    });
+    el.addEventListener("flow-ui-change", () => {
+      if (updateOn === "change") {
+        this.set(statePath, toState(el.value));
+      }
+    });
+    return this.toStream(statePath, true).subscribe((value) => {
+      if (value !== el.value) {
+        el.value = fromState(value);
+      }
+    });
+  }
+  /**
+   * Bind an HTML element property to a state store property. One-way binding
+   * is established between the element property and the state store property.
+   * When the state store property changes, the element property is updated.
+   *
+   * :::warning
+   * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+   * :::
+   *
+   * :::warning
+   * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+   * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+   * :::
+   *
+   * @example
+   * ```js
+   * const el = document.getElementById('my-span');
+   * const subscription = store.bindElementProp(el, 'textContent', 'myStateProperty');
+   * ...
+   * subscription.unsubscribe();
+   * ```
+   *
+   * @param el - The HTML element to bind
+   * @param prop - The property of the element to bind
+   * @param path - The path to the state store property to bind
+   * @param options - Binding options
+   * @param options.fromState - A function to convert the state store value to the element property value
+   * @returns A subscription that can be used to `unsubscribe()` the binding.
+   */
+  bindElementProp(el, prop, path, options) {
+    const fromState = options?.fromState ?? ((v) => v);
+    return this.toStream(path, true).subscribe((value) => {
+      if (value !== el[prop]) {
+        el[prop] = fromState(value);
+      }
+    });
+  }
+  /**
+   * Bind an HTML element attribute to a state store property. One-way binding
+   * is established between the element attribute and the state store property.
+   * When the state store property changes, the element attribute is updated
+   * (using `el.setAttribute(...)`).
+   *
+   * :::warning
+   * Bindings should be disposed of when no longer needed by calling `unsubscribe()` on the returned subscription.
+   * :::
+   *
+   * :::warning
+   * This method is provided to support reactive binding for vanilla JS and TS applications. When using
+   * other supported frameworks (e.g. Angular) use the preferred binding method for that framework.
+   * :::
+   *
+   * @param el - The HTML element to bind
+   * @param attr - The attribute of the element to bind
+   * @param path - The path to the state store property to bind
+   * @returns
+   */
+  bindElementAttr(el, attr, path, options) {
+    const fromState = options?.fromState ?? ((v) => v.toString ? v.toString() : v);
+    return this.toStream(path, true).subscribe((value) => {
+      el.setAttribute(attr, fromState(value));
+    });
+  }
+  /**
+   * Create an observable stream that emits the value of the specified state store property
+   * when it changes. The stream can be subscribed to using its `subscribe()` method.
+   *
+   * :::warning
+   * Subscriptions should be disposed of when no longer required by calling their `unsubscribe()` method.
+   * :::
+   *
+   * :::danger
+   * It is an anti-pattern to modify state store properties directly from within a stream subscription.
+   * Use a `computed` property instead. Limit use of `toStream` to running imperative side-effects
+   * in response to a reactive update of a state property.
+   * :::
+   *
+   * @example
+   * ```js
+   * const subscription = store.toStream('myStateProperty').subscribe((value) => {
+   *  console.log('myStateProperty changed:', value);
+   * });
+   * ...
+   * subscription.unsubscribe();
+   * ```
+   *
+   * @param path - The path to the state store property to bind
+   * @param fireImmediately - If `true`, the stream will emit the current value immediately
+   * If `false`, the stream will only emit values when the state store property changes.
+   *
+   * @returns An observable stream that emits the value of the specified state property.
+   */
+  toStream(path, fireImmediately = true) {
+    this.checkInitialized();
+    return toStream(() => this.get(path), fireImmediately);
+  }
+  /**
+   * Creates a reactive context that will automatically re-run the specified function
+   * whenever referenced reactive state changes. The supplied function is run immediately
+   * and referenced state properties are tracked. The function will be re-run when tracked
+   * state properties change.
+   *
+   * Note that referenced state properties are determined dynamically
+   * by access. If a code branch is not taken, the referenced state properties in that branch
+   * will not be tracked. If, on a subsequent run, the code branch is taken, the tracking
+   * will be updated to include the newly accessed state properties.
+   *
+   * This method is similar to `toStream` but allows access to the complete state object rather
+   * than a single property.
+   *
+   * :::warning
+   * Autoruns should be disposed of when no longer needed by invoking the `disposer` function
+   * returned when creating an autorun.
+   * :::
+   *
+   * :::danger
+   * It is an anti-pattern to modify state store properties directly from within an autorun.
+   * Use a `computed` property instead. Limit use of autoruns to running imperative side-effects
+   * in response to a reactive update.
+   * :::
+   *
+   * @example
+   * ```js
+   * const disposer = store.autorun((state) => {
+   *    // Set map properties as a side effect whenever any of `state.zoom`, `state.bearing`, or `state.pitch` change
+   *    map.setCenter({zoom: state.zoom, bearing: state.bearing, pitch: state.pitch});
+   * });
+   * ...
+   * disposer();
+   * ```
+   *
+   * @param autorunFn - The function to run within a reactive context
+   * @param name - Optional name for debugging purposes
+   * @returns - A disposer function. Invoke this function to dispose of the autorun.
+   */
+  autorun(autorunFn, name) {
+    this.checkInitialized();
+    return mobx.autorun(() => autorunFn(this), { name });
+  }
+  /**
+   * This method **must**
+   *  be called in the constructor of derived classes to initialize the state store.
+   * An exception will be thrown if this method is not called before using the state store.
+   *
+   * If using decorators to configure reactive properties, this method should be called without arguments.
+   * If not using decorators, supply reactive annotations to configure reactive properties.
+   *
+   * See {@link StoreAnnotations} for a list of available annotations.
+   *
+   * :::info
+   * If this method is called without using decorators and without supplying reactive annotations,
+   * the state store will be configured automatically:
+   *
+   * - All properties will be made observable.
+   * - All getters will converted to computed properties.
+   *
+   * This is only recommended for simple state stores in demos.
+   * :::
+   *
+   * @param annotations Optional annotations for configuring reactive properties.
+   */
+  initialize(annotations = {}) {
+    if (this.initialized) {
+      throw new FlowCoreError(`${this.formattedName}: store has already been initialized`);
+    }
+    const annotationsByType = {
+      [REACTIVE_ANNOTATION_TYPE]: collectStoredAnnotations(this, REACTIVE_ANNOTATION_TYPE),
+      [SYNC_ANNOTATION_TYPE]: collectStoredAnnotations(this, SYNC_ANNOTATION_TYPE)
+    };
+    Object.keys(annotations).forEach((prop) => {
+      const propAnnotations = ensureArray(annotations[prop]);
+      propAnnotations.forEach((annotation) => {
+        const type = annotation.annotationType;
+        annotationsByType[type] ?? (annotationsByType[type] = {});
+        annotationsByType[type][prop] = annotation;
+      });
+    });
+    this.serializationAnnotations = annotationsByType[SYNC_ANNOTATION_TYPE];
+    if (Object.keys(annotationsByType[REACTIVE_ANNOTATION_TYPE]).length) {
+      const mobxAnnotations = Object.keys(annotationsByType[REACTIVE_ANNOTATION_TYPE]).reduce((accum, prop) => {
+        accum[prop] = annotationsByType[REACTIVE_ANNOTATION_TYPE][prop].mobxAnnotation;
+        return accum;
+      }, {});
+      const reactivity = Object.keys(mobxAnnotations).reduce((accum, prop) => {
+        accum[prop] = mobxAnnotations[prop].annotationType_;
+        return accum;
+      }, {});
+      const serialization = Object.keys(annotationsByType[SYNC_ANNOTATION_TYPE]).reduce((accum, prop) => {
+        accum[prop] = annotationsByType[SYNC_ANNOTATION_TYPE][prop].syncType;
+        return accum;
+      }, {});
+      this.makeObservable(mobxAnnotations);
+      debug(`${this.formattedName}: initialized with annotations`, {
+        reactivity,
+        serialization
+      });
+    } else {
+      this.makeAutoObservable();
+      debug(`${this.formattedName}: initialized with auto-annotations`);
+    }
+  }
+  /**
+   * Serialize the state store properties that have been annotated as serializable to an object or string.
+   *
+   * The following formats are supported:
+   * - `raw` (default): Plain object with property values serialized as JSON strings.
+   * - `json`: The `raw` object format serialized as a single JSON string.
+   * - `lz`: The `raw` object format serialized as a single JSON string and then compressed using [lzString.compressToEncodedURIComponent](https://github.com/pieroxy/lz-string).
+   *
+   * The `lz` format is designed for serializing state store properties to a URL query string.
+   */
+  serialize(format = "raw", group) {
+    const annotations = this.serializationAnnotations;
+    const serializedProps = Object.keys(annotations).reduce((accum, prop) => {
+      const annotationGroup = ensureArray(annotations[prop].arg);
+      const annotationType = annotations[prop].type;
+      if (group && annotationType !== "state" && !annotationGroup.includes(group)) {
+        return accum;
+      }
+      const val = this[prop];
+      if (isDefined(val)) {
+        const serializedValue = annotations[prop].serialize(val, group);
+        accum[prop] = serializedValue;
+      }
+      return accum;
+    }, {});
+    switch (format) {
+      case "json":
+        return JSON.stringify(serializedProps);
+      case "lz":
+        return lzString.compressToEncodedURIComponent(JSON.stringify(serializedProps));
+      default:
+        return serializedProps;
+    }
+  }
+  /**
+   * Set state store properties by deserializing from serialized output of the {@link serialize} method.
+   * Only properties that have been annotated as serializable and are present in the serialized value will be deserialized.
+   * Other properties will be left unchanged.
+   */
+  deserialize(value, format = "raw") {
+    let deserializedValue;
+    switch (format) {
+      case "json":
+        deserializedValue = JSON.parse(value);
+        break;
+      case "lz":
+        deserializedValue = JSON.parse(lzString.decompressFromEncodedURIComponent(value));
+        break;
+      default:
+        deserializedValue = value;
+        break;
+    }
+    this.transaction(() => {
+      const annotations = this.serializationAnnotations;
+      Object.keys(deserializedValue).forEach((prop) => {
+        const annotation = annotations[prop];
+        if (annotation) {
+          this[prop] = annotation.deserialize(deserializedValue[prop], this[prop]);
+        }
+      });
+    });
+  }
+  makeObservable(overrides) {
+    if (this.initialized) {
+      throw new FlowCoreError(`${this.formattedName}: store is already observable`);
+    }
+    overrides = {
+      ...overrides,
+      set: mobx.action,
+      toggle: mobx.action,
+      increment: mobx.action,
+      decrement: mobx.action
+    };
+    mobx.makeObservable(this, overrides, { name: this.formattedName });
+  }
+  makeAutoObservable(overrides = {}) {
+    if (this.initialized) {
+      throw new FlowCoreError(`${this.formattedName}: store is already observable`);
+    }
+    const target = this;
+    overrides = {
+      ...overrides,
+      _initialized: false,
+      $mobx: false,
+      constructor: false
+    };
+    let annotations = target[StateStorCache];
+    if (!annotations) {
+      annotations = {};
+      let current = target;
+      while (current && !Object.prototype.hasOwnProperty.call(current, StateStoreMarker)) {
+        Reflect.ownKeys(current).forEach((k) => {
+          annotations[k] = !overrides ? true : k in overrides ? overrides[k] : true;
+        });
+        current = Object.getPrototypeOf(current);
+      }
+      const proto = Object.getPrototypeOf(target);
+      if (proto) {
+        Object.defineProperty(proto, StateStorCache, { value: annotations });
+      }
+    }
+    annotations = {
+      ...annotations,
+      set: mobx.action,
+      toggle: mobx.action,
+      increment: mobx.action,
+      decrement: mobx.action
+    };
+    return mobx.makeObservable(target, annotations, { name: this.formattedName });
+  }
+  checkInitialized() {
+    if (!this.initialized) {
+      throw new FlowCoreError(
+        `${this.formattedName} not initialized. Please use one of the recommended methods to make this state store observable.`
+      );
+    }
+  }
+}
+StateStore.prototype[StateStoreMarker] = true;
+
+export { StateStore };

package/dist/lib/state-store/utils.mjs

@@ -0,0 +1,7 @@
+import { trace } from 'mobx';
+
+function traceReaction() {
+  trace();
+}
+
+export { traceReaction };

package/dist/lib/utils/announce.mjs

@@ -0,0 +1,12 @@
+import { version } from '../../package.json.mjs';
+
+const CONSOLE_HIGHLIGHT_STYLE = `
+  padding: 2px 4px;
+  border-radius: 2px;
+  background: #389DFF;
+  color: white;`;
+function announce() {
+  console.log("%cFlo.w RDF Core v%s", CONSOLE_HIGHLIGHT_STYLE, version);
+}
+
+export { announce as default };

package/dist/lib/utils/assert.mjs

@@ -0,0 +1,12 @@
+import { FlowCoreError } from '../errors/flow-error.mjs';
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new FlowCoreError(message ?? "Assertion failed");
+  }
+}
+function die(message) {
+  throw new FlowCoreError(message);
+}
+
+export { assert, die };

package/dist/{shared/flow-rdf-core.187cb345.mjs → lib/utils/debounce.mjs}

@@ -1,25 +1,5 @@
-import { o as isNumber } from './flow-rdf-core.25e5f6d7.mjs';
-
-const doNotMemoize = Symbol("Do not memoize");
-function memoize(originalFunction, options) {
-  const cache = /* @__PURE__ */ new Map();
-  const hash = options.hash ? options.hash : (...args) => args[0];
-  const context = options.context;
-  return function memoizedFunction(...args) {
-    const key = hash.apply(context, args);
-    if (key === doNotMemoize) {
-      return originalFunction.apply(context, args);
-    }
-    let value;
-    if (!cache.has(key)) {
-      value = originalFunction.apply(context, args);
-      cache.set(key, value);
-    } else {
-      value = cache.get(key);
-    }
-    return value;
-  };
-}
+import { memoize } from './functional.mjs';
+import { isNumber } from './type-checks.mjs';
 
 function debounce(func, wait, options) {
   options = {
@@ -125,20 +105,4 @@ function debounceWithArgs(fn, wait, options) {
   };
 }
 
-function throttle(func, wait, options) {
-  if (typeof func != "function") {
-    throw new TypeError("Expected a function");
-  }
-  return debounce(func, wait, { ...options, maxWait: wait });
-}
-function throttleWithArgs(fn, wait, options) {
-  const memoizedThrottleFn = memoize(
-    () => debounce(fn, wait, options),
-    options
-  );
-  return (...args) => {
-    memoizedThrottleFn(...args)(...args);
-  };
-}
-
-export { debounceWithArgs as a, throttleWithArgs as b, debounce as d, memoize as m, throttle as t };
+export { debounce, debounceWithArgs, debounce as default };