@lumjs/core 1.38.1 → 1.38.3

package/lib/arrays/index.js

@@ -4,7 +4,7 @@
  * @module @lumjs/core/arrays
  */
 
-const {lazy} = require('../types');
+const {lazy} = require('../obj/df');
 const {powerset, random} = require('./util');
 
 // Utils.

package/lib/arrays/typed.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const {F, isObj, isPlainObject} = require('../types/basics');
+const Enum = require('../enum');
+const TypedArray = Object.getPrototypeOf(Int8Array);
+const CT = Enum(['GT','LT','ALL'], {flags: true});
+
+/**
+ * An Enum object with bitwise flags for the `opts.convert` argument
+ * of the makeType() function.
+ * 
+ * @name module:@lumjs/core/arrays.ConvertType
+ * @type {object}
+ * @prop {number} GT - Convert any values which have a larger bytes per 
+ *   element size than the `opts.type` TypedArray class.
+ * @prop {number} LT - Convert any values which have a smaller bytes per 
+ *   element size than the `opts.type` TypedArray class.
+ * @prop {number} ALL - Convert all values that aren't already instances
+ *   of the `opts.type` class.
+ *   Note: if you use this flag, then the other flags are ignored!
+ *
+ */
+
+/**
+ * Build a new TypedArray with multiple input values.
+ * 
+ * @alias module:@lumjs/core/arrays.makeTyped
+ * 
+ * @param {(object|function)} [opts] - Options.
+ * 
+ * If this is a `function` then it is assumed to be the `opts.type` value.
+ * 
+ * If this is anything other than a _plain object_ (i.e. it was created
+ * with a class constructor rather than `{}` literal syntax), then it will
+ * be considered an element of the `inValues` parameter instead of options.
+ * 
+ * @param {function} [opts.type=Uint8Array] TypedArray class to return.
+ * @param {number}   [opts.convert=0]       Convert TypedArrays before merge?
+ * 
+ * By default all TypedArray objects passed (or created by the TextEncoder) 
+ * will be added to the new TypedArray as-is, which may result in data 
+ * corruption if the unit byte-size of the source TypeArray is larger 
+ * than the newly created TypeArray. If the unit byte-size of the requested
+ * type is the same or larger than any input sources, then it doesn't matter.
+ * 
+ * You can however convert all source TypedArray objects to the `opts.type`
+ * class using an intermediary ArrayBuffer, and choose the criteria for
+ * the conversion by specifying various bitwise flags in this option.
+ * 
+ * Use the properties of the `ConvertType` Enum as the flag values.
+ * 
+ * e.g.: `makeTyped({convert: ConvertType.GT | ConvertType.LT}, ...values);`
+ * 
+ * WARNING: The type conversion methodology is not the greatest and doesn't
+ * cover every possible issue, so don't be surprised if you end up with
+ * corrupted data (or you have an Exception thrown) when mixing different
+ * TypeArray classes. If at all possible, only merge values of the same type.
+ * 
+ * @param {...mixed} inValues - Values to be added to the new TypeArray.
+ * 
+ * If the value is considered a _View_ (i.e. a TypedArray or DataView),
+ * it will be used directly.
+ * 
+ * Any other kind of `object` will be serialized using JSON and then
+ * encoded into a Uint8Array using TextEncoder.
+ * 
+ * Any other type of value will be encoded using TextEncoder, which will
+ * call `value.toString()` on any non-string values before encoding.
+ * 
+ * @returns {TypedArray}
+ * 
+ * @throws {TypeError} If `opts.type` is not a TypedArray constructor.
+ * @throws {RangeError} If the byte length of any of the `inValues`
+ *   is not an integral multiple of the `opts.type` bytes per element size.
+ * 
+ */
+function makeTyped(opts, ...inValues) 
+{
+  if (typeof opts === F) 
+  {
+    opts = {type: opts};
+  }
+  else if (isPlainObject(opts)) 
+  {
+    inValues.unshift(opts);
+    opts = {};
+  }
+
+  let wantType = opts.type    ?? Uint8Array;
+  let convert  = opts.convert ?? 0;
+
+  if (typeof wantType !== F || !TypedArray.isPrototypeOf(wantType))
+  {
+    console.error({wantType, opts, inValues});
+    throw new TypeError("Invalid TypedArray class");
+  }
+
+  let fullLen = 0;
+  let tenc = new TextEncoder();
+  let wantSize = wantType.BYTES_PER_ELEMENT;
+
+  let mergeValues = inValues.map(value => 
+  {
+    if (!ArrayBuffer.isView(value)) 
+    {
+      if (isObj(value)) 
+      {
+        value = JSON.stringify(value);
+      }
+      value = tenc.encode(value); 
+    }
+
+    let valSize = value.constructor.BYTES_PER_ELEMENT;
+
+    if ( ((convert & CT.ALL) && !(value instanceof wantType))
+      || ((convert & CT.GT)  && valSize > wantSize) 
+      || ((convert & CT.LT)  && valSize < wantSize)) 
+    { // Convert value to our wanted type
+      value = new wantType(value.buffer);
+    }
+
+    fullLen += value.byteLength;
+
+    return value;
+  });
+
+  let output = new wantType(new ArrayBuffer(fullLen));
+  let offset = 0;
+
+  for (let value of mergeValues) 
+  {
+    output.set(value, offset);
+    offset += value.length;
+  }
+
+  return output;
+}
+
+module.exports = {makeTyped, ConvertType: CT, TypedArray}

package/lib/events/index.js

@@ -1,93 +1,126 @@
 /**
  * A simplistic event registration and dispatch module.
- * 
- * Designed to be a replacement for the `observable` API which started
- * out simple enough (when I forked it from `riot.js`), but has since 
- * grown into a big mess with many unusual and unexpected behaviours.
- * 
- * So this has been designed to work with a cleaner, more consistent,
- * yet extremely flexible event model.
- * 
  * @module @lumjs/core/events
+ * @deprecated Moved to @lumjs/events and @lumjs/events-observable packages.
  */
+'use strict';
 
-const lazy = require('../types/lazy');
+const Events = require('@lumjs/events');
+const {lazy} = require('../obj/df');
 
-exports = module.exports =
+exports = module.exports = Object.assign(
 {
-  Registry: require('./registry'),
-  Listener: require('./listener'),
-  Event: require('./event'),
-
-  /**
-   * A shortcut function to create a new Registry instance.
-   * All arguments are passed to the Registry constructor.
-   * @param {(object|module:@lumjs/core/events~GetTargets)} targets
-   * @param {object} [opts]
-   * @returns {module:@lumjs/core/events.Registry}
-   */
-  register(targets, opts)
-  {
-    return new exports.Registry(targets, opts);
-  },
-
-  /**
-   * Create a registry for a single target object, then return the target.
-   * @param {object} target 
-   * @param {object} [opts] 
-   * @returns {object} `target`
-   */
-  extend(target, opts)
-  {
-    exports.register([target], opts);
-    return target;
-  },
-
   /**
    * Apply the compatibility version of the observable API;
    * will load the events/observable sub-module on demand.
+   * @name module:@lumjs/core/events.observable
    * @param {object} target
    * @param {object} [opts]
    * @returns {object} `target`
-   * @see module:@lumjs/core/events/observable.makeObservable
+   * @deprecated Use the @lumjs/events-observable package.
    */
   observable(target, opts)
   {
     const {makeObservable} = exports.Observable;
     return makeObservable(target, opts);
   },
+}, Events);
 
-  /**
-   * See if an object has a known trigger method.
-   * 
-   * Currently will look for one of:
-   * 
-   * - `emit`
-   * - `trigger`
-   * 
-   * @param {object} obj - Object we want to find a trigger method on
-   * 
-   * @returns {?string} The name of the method found,
-   * or null if none found.
-   */
-  hasTrigger(obj)
-  {
-    for (const trigger of exports.KNOWN_TRIGGERS)
-    {
-      if (typeof obj[trigger] === F)
-      {
-        return trigger;
-      }
-    }
-    
-    return null;
-  },
+lazy(exports, 'Observable', () => require('./observable'));
 
-  /**
-   * The list of known trigger method names for `hasTrigger()`
-   */
-  KNOWN_TRIGGERS: ['emit','trigger'],
+/**
+ * An Event object to emit to handler callbacks.
+ * 
+ * @class module:@lumjs/core/events.Event
+ * 
+ * @prop {module:@lumjs/core/events.Listener} eventListener
+ * The event Listener instance this event was emitted from.
+ * @prop {(string|Symbol)} type - The event type that was triggered.
+ * @prop {string} name - The event name that was triggered;
+ * if `type` is a string this will be the same value,
+ * for a Symbol type this will be the `type.description` value.
+ * @prop {object} target - Target object for this event.
+ * @prop {Array} args - Arguments passed to `emit()`
+ * @prop {object} options - Composes options from the
+ * Registry and the Listener. Listener options take priority.
+ * @prop {?object} data 
+ * If `args[0]` is any kind of `object` other than another Event 
+ * instance, it will be used as the `data` property. 
+ * If `args[0]` is not an `object`, this property will be `null`.
+ * @prop {module:@lumjs/core/events.Event} origEvent
+ * Unless `this.prevEvent` is set, this should always be
+ * a reference to `this` instance itself.
+ * @prop {?module:@lumjs/core/events.Event} prevEvent
+ * If `args[0]` is another Event instance this property
+ * will be set with its value, as well as the following
+ * changes to the default behavior:
+ * 
+ * - `this.data` will be set to `prevEvent.data`.
+ * - `this.origEvent` will be set to `prevEvent.origEvent`
+ * 
+ * @prop {module:@lumjs/core/events~Status} emitStatus
+ *
+ * @deprecated Moved to @lumjs/events package.
+ */
 
-}
+/**
+ * An Event Listener instance used by a Registry
+ * 
+ * Used internally by the Registry class, there's likely very few 
+ * reasons you'd want to call any methods on this manually.
+ * 
+ * @class module:@lumjs/core/events.Listener
+ * 
+ * @prop {module:@lumjs/core/events.Registry} registry 
+ * The Registry instance this Listener belongs to.
+ * @prop {(function|object)} handler - Event handler callback
+ * @prop {Set} eventTypes - A set of all event types handled by this
+ * @prop {Set} eventNames - Alias to `eventTypes`
+ * @prop {object} options - Options specific to this listener.
+ * 
+ * @deprecated Moved to @lumjs/events package.
+ */
 
-lazy(exports, 'Observable', () => require('./observable'));
+/**
+ * A class that handles events for target objects
+ * 
+ * @class module:@lumjs/core/events.Registry
+ * 
+ * @prop {module:@lumjs/core/events~GetTargets} getTargets 
+ * A constructor-assigned callback method that returns a set of targets.
+ * @prop {object} options - Registry-level options
+ * @prop {Set.<module:@lumjs/core/events.Listener>} allListeners
+ * All registered event listeners
+ * @prop {Map.<string,Set.<module:@lumjs/core/events.Listener>>} listenersFor
+ * Each key is a single event name, and the value is a Set of
+ * listener objects that handle that event.
+ * 
+ * @deprecated Moved to @lumjs/events package.
+ */
+
+/**
+ * A shortcut function to create a new Registry instance.
+ * All arguments are passed to the Registry constructor.
+ * @function module:@lumjs/core/events.register
+ * @param {(object|module:@lumjs/core/events~GetTargets)} targets
+ * @param {object} [opts]
+ * @returns {object} A @lumjs/events.Registry instance.
+ * @deprecated Moved to @lumjs/events package.
+ */
+
+/**
+ * Create a registry for a single target object, then return the target.
+ * @function module:@lumjs/core/events.extend
+ * @param {object} target 
+ * @param {object} [opts] 
+ * @returns {object} `target`
+ * @deprecated Moved to @lumjs/events package.
+ */
+
+/**
+ * See if an object has a known trigger method.
+ * @function module:@lumjs/core/events.hasTrigger
+ * @param {object} obj - Object we want to find a trigger method on
+ * @returns {?string} The name of the method found
+ * @deprecated Moved to @lumjs/events package.
+ */

package/lib/events/observable.js

@@ -1,243 +1,8 @@
 /**
  * Observable Compatibility API
  * @module @lumjs/core/events/observable
+ * @deprecated Moved to @lumjs/events-observable package.
  */
 "use strict";
 
-const {B,F,S,def,isComplex,TYPES} = require('../types');
-const lock = Object.freeze;
-const copy = Object.assign;
-const Registry = require('./registry');
-
-const ISOB = 'isObservable';
-
-const OBS_EXTENDS =
-{
-  registry: '$events',
-  listen:   'on',
-  emit:     'trigger',
-  remove:   'off',
-  once:     'one',
-}
-
-const OBS_OPTIONS =
-{
-  wrapargs: false,
-  wrapthis: false,
-  wraplock: true,
-  wrapsetup: null,
-  addme: null,
-  // addname: !(wrapargs || wrapthis)
-  // addis:    (wrapargs || wrapthis)
-}
-
-/**
- * A version of the observable API using the events module.
- * 
- * It's obviously not going to be 100% identical due to
- * the very different nature of the backend engine, but it'll
- * try its best to make existing code work.
- * 
- * A few obscure features that I don't think are particularly
- * important and won't affect *most* exising uses will be dropped.
- * 
- * @param {(object|function)} el - The target to add observable API to.
- * 
- * @param {object} [oo] 
- * {@link module:@lumjs/core/observable Observable} options
- * 
- * @param {boolean} [oo.addwrap] If this is `true`, 
- * and `oo.wrapargs` is `false`, then the `event` object 
- * will be appended to the arguments sent to the handler.
- * 
- * The default value is: `!oo.wrapthis`
- * 
- * @param {object} [ro]
- * {@link module:@lumjs/core/events.Registry Registry} options;
- * 
- * The `setupEvent` and `setupListener` options cannot be specified,
- * as the versions from this module will always be used.
- * 
- * The `extend` defaults are changed to match those used
- * by the observable API (`on`,`trigger`,`off`,`one`),
- * and `extend.registry` is set to `$events` by default.
- * 
- * Setting the `extend` option to `false` will have no effect
- * in this implementation.
- * 
- * @param {boolean} [wantReg=false] Return the Registry?
- * @returns {object} normally `el`, unless `wantReg` was `true`
- * @see module:@lumjs/core/observable~API
- * @alias module:@lumjs/core/events/observable.makeObservable
- */
-function makeObservable(el, oo, ro, wantReg=false)
-{
-  if (!isComplex(el))
-  {
-    throw new TypeError("el was not an object or function");
-  }
-
-  ro = copy({}, ro);
-  ro.extend = copy({}, OBS_EXTENDS, ro.extend);
-  ro.setupEvent = setupEvent;
-  ro.setupListener = setupListener;
-  oo = ro.observable = copy({}, OBS_OPTIONS, oo);
-
-  let wrapped = (oo.wrapargs || oo.wrapthis);
-  if (!wrapped && typeof oo.wrapsetup === F)
-  {
-    wrapped = oo.wrapargs = true;
-  }
-
-  if (typeof oo.wildcard === S)
-  { // oo.wildcard takes precedence
-    ro.wildcard = oo.wildcard;
-  }
-
-  const setIf = (opt, get) => 
-  {
-    if (typeof oo[opt] !== B)
-    {
-      oo[opt] = get();
-    }
-  }
-
-  setIf('addname', () => !wrapped);
-  setIf('addis',   () =>  wrapped);
-  setIf('addwrap', () => !oo.wrapthis);
-
-  const reg = new Registry([el], ro);
-
-  if (oo.addis)
-  {
-    def(el, ISOB, lock({event: false, target: true}));
-  }
-
-  if (typeof oo.addme === S)
-  {
-    def(el, oo.addme, function(el2, oo2, ro2)
-    {
-      return makeObservable(el2, 
-        copy({}, oo, oo2),
-        copy({}, ro, ro2)
-      );
-    });
-  }
-
-  return wantReg ? reg : el;
-}
-
-/**
- * Event setup for observable compatibility
- * @type {module:@lumjs/core/events~SetupEvent}
- * @alias module:@lumjs/core/events/observable.setupEvent
- */
-function setupEvent(ev)
-{
-  const ro = this.registry.options;
-  const oo = ro.observable;
-  ev.wildcard = this.eventNames.has(ro.wildcard);
-  ev.self = ev.target;
-  ev.type = ev.name;
-  def(ev, ISOB, lock({event: true, target: false}));
-
-  if (typeof oo.wrapsetup === F)
-  {
-    oo.wrapsetup.call(ev.target, ev);
-  }
-
-  if (oo.wraplock)
-  {
-    lock(ev);
-  }
-}
-
-/**
- * Listener setup for observable compatibility
- * @type {module:@lumjs/core/events~SetupListener}
- * @alias module:@lumjs/core/events/observable.setupListener
- */
-function setupListener(ln)
-{
-  const oo = this.options.observable;
-  const oh = ln.observableHandler = ln.handler;
-  const go = (ev, args) => 
-  {
-    if (typeof oh === F)
-    {
-      const thisTarget = oo.wrapthis ? ev : ev.target;
-      oh.apply(thisTarget, args);
-    }
-    else
-    {
-      oh.handleEvent(...args);
-    }
-  }
-
-  if (!oo.wrapargs)
-  { // Not wrapping args, we need to wrap the handler.
-    const ec = ln.eventNames.size;
-    ln.handler = function(ev)
-    {
-      const args = ev.args;
-      if (ec > 1 && oo.addname)
-      {
-        args.unshift(ev.name);
-      }
-      if (oo.addwrap)
-      {
-        args.push(ev);
-      }
-
-      go(ev, args);
-    }
-  }
-  else if (oo.wrapthis)
-  { // Both wrapargs and wrapthis are in use, woah!
-    ln.handler = function(ev)
-    {
-      go(ev, [ev]);
-    }
-  }
-}
-
-/**
- * See if a value appears to implement the observable API.
- * 
- * This is a simple function that relies on duck-typing,
- * and only looks for `trigger` and `on` methods.
- * 
- * @param {(object|function)} obj - Value to check for observable API
- * @returns {boolean}
- * @alias module:@lumjs/core/events/observable.isObservable
- */
-function isObservable(obj)
-{
-  return (isComplex(obj)
-    && typeof obj.trigger === F
-    && typeof obj.on === F);
-}
-
-// Undocumented alias for the sake of compatibility.
-def(makeObservable, 'is', isObservable);
-
-/**
- * Does a value implement the Observable interface?
- * @name module:@lumjs/core/types.doesObservable
- * @function
- * @param {*} v - The expected object/function to test.
- * @returns {boolean}
- * @see module:@lumjs/core/events/observable.isObservable
- */
-
-/**
- * Extension type for the {@link module:@lumjs/core/observable~API} interface.
- * @memberof module:@lumjs/core/types.TYPES
- * @member {string} OBSERV - Implements the *Observable* interface.
- */
-TYPES.add('OBSERV', 'observable', isObservable, 'doesObservable');
-
-module.exports =
-{
-  makeObservable, setupEvent, setupListener, isObservable,
-}
+module.exports = require('@lumjs/events-observable');

package/lib/index.js

@@ -12,33 +12,34 @@
 
 /// see also: `docs/src/index.js`
 
+const types = require('./types');
+const {df,lazy} = require('./obj/df');
+
 // Get a bunch of properties from a submodule.
 function from(submod)
 {
   for (const key in submod)
   {
-    def(exports, key, submod[key]);
+    df(exports, key, submod[key]);
   }
 }
 
-const types = require('./types');
-const {def,lazy} = types;
-
-def(exports, 'types', types);
-def(exports, 'def',   def);
-def(exports, 'lazy',  lazy);
+df(exports, 'types', types);
+df(exports, 'def',   types.def);
+df(exports, 'df',    df);
+df(exports, 'lazy',  lazy);
 
-def(exports, 'context', require('./context'));
-def(exports, 'state', {value: require('./state')});
+df(exports, 'context', require('./context'));
+df(exports, 'state', {value: require('./state')});
 
 // ObjectID stuff is imported directly without registering a sub-module.
 from(require('./objectid'));
 
 // These are exported directly, but a meta sub-module also exists.
-// Unlike most sub-modules there is no `meta` property in the main library.
 const meta = require('./meta');
 from(meta);
-def(exports, 'AbstractClass', 
+df(exports, 'meta', meta);
+df(exports, 'AbstractClass', 
 {
   get() { return meta.AbstractClass; }
 });
@@ -50,7 +51,7 @@ lazy(exports, 'flags', () => require('./flags'));
 lazy(exports, 'obj', () => require('./obj'));
 lazy(exports, 'console', () => require('./console'));
 lazy(exports, 'traits', () => require('./traits'));
-lazy(exports, 'opt', () => require('./opt'), {def:{autoDesc: false}});
+lazy(exports, 'opt', () => require('./opt'), {df:{autoDesc: false}});
 lazy(exports, 'Enum', () => require('./enum'));
 lazy(exports, 'observable', () => require('./observable'));
 lazy(exports, 'events', () => require('./events'));

package/lib/meta.js

@@ -191,7 +191,7 @@ function wrapDepr(obj,prop,spec)
   if (typeof spec.get !== F) 
     throw new TypeError("invalid init");
 
-  return def(obj, prop, 
+  return df(obj, prop, 
   {
     get: () =>
       deprecated(spec.dep??prop, spec.rep, spec.get())
@@ -201,6 +201,6 @@ function wrapDepr(obj,prop,spec)
 exports.wrapDepr = wrapDepr;
 
 // This is near the bottom, but before any calls to wrapDepr.
-const def = require('./types/def');
+const {df} = require('./obj/df');
 
 wrapDepr(exports, 'AbstractClass', () => require('./old/abstractclass'));