@lumjs/core 1.38.7 → 1.39.0

package/lib/arrays/add.js

@@ -1,233 +0,0 @@
-
-const {N,def} = require('../types');
-
-/**
- * Functions for adding values to arrays in different ways.
- * @alias module:@lumjs/core/arrays.add
- */
-const ArrayAdd = module.exports = exports =
-{
-  prepend, before, append, after, insert,
-}
-
-function _addWith(array, oldValue, newValue, ifMissing, fn)
-{
-  let pos = array.indexOf(oldValue);
-
-  if (pos === -1)
-  {
-    if (typeof ifMissing === N)
-    {
-      pos = ifMissing;
-    }
-    else
-    {
-      return false;
-    }
-  }
-
-  return fn(array, newValue, pos);
-}
-
-/**
- * Prepend a value to an array.
- * 
- * @param {Array} array - Array to add the value to.
- * @param {*}     value - Value to add to the array.
- * @param {number} [pos=0] Position to prepend at.
- * 
- * If `pos` is `0` then `array.unshift(value)` is used.
- * Otherwise `array.splice(pos, 0, value)` is used.
- * 
- * @returns {Array} `array`
- * @alias module:@lumjs/core/arrays.add.prepend
- */
-function prepend(array, value, pos=0)
-{
-  if (pos === 0)
-  {
-    array.unshift(value);
-  }
-  else
-  {
-    array.splice(pos, 0, value);
-  }
-
-  return array;
-}
-
-/**
- * Append a value to an array.
- * 
- * @param {Array} array - Array to add the value to.
- * @param {*}     value - Value to add to the array.
- * @param {number} [pos=-1] Position to append at.
- * 
- * If `pos` is `-1` then `array.push(value)` is used.
- * Otherwise `array.splice(pos+1, 0, value)` is used.
- * 
- * @returns {Array} `array`
- * @alias module:@lumjs/core/arrays.add.append
- */
-function append(array, value, pos=-1)
-{
-  if (pos === -1)
-  {
-    array.push(value);
-  }
-  else
-  {
-    array.splice(pos+1, 0, value);
-  }
-
-  return array;
-}
-
-/**
- * Add a value to an array _before_ an existing value.
- * 
- * This uses `prepend()` to add the value.
- * 
- * @param {Array} array - Array to add the value to.
- * @param {*} oldValue  - Existing value to find.
- * @param {*} newValue  - Value to add to the array.
- * @param {(number|false)} [ifMissing=0] If `oldValue` is not found.
- * 
- * If this is a `number` it will be used as the `pos` argument.
- * 
- * If this is `false` the function will not add the value at all,
- * but will return `false` instead.
- * 
- * @returns {(Array|false)} Usually the input `array`; but will return
- * `false` if `ifMissing` was `false` and the `oldValue` was not found.
- * 
- * @alias module:@lumjs/core/arrays.add.before
- */
-function before(array, oldValue, newValue, ifMissing=0)
-{
-  return _addWith(array, oldValue, newValue, ifMissing, prepend);
-}
-
-/**
- * Add a value to an array _after_ an existing value.
- * 
- * This uses `append()` to add the value.
- * 
- * @param {Array} array - Array to add the value to.
- * @param {*} oldValue  - Existing value to find.
- * @param {*} newValue  - Value to add to the array.
- * @param {(number|false)} [ifMissing=-1] If `oldValue` is not found.
- * 
- * If this is a `number` it will be used as the `pos` argument.
- * 
- * If this is `false` the function will not add the value at all,
- * but will return `false` instead.
- * 
- * @returns {(Array|false)} Usually the input `array`; but will return
- * `false` if `ifMissing` was `false` and the `oldValue` was not found.
- * 
- * @alias module:@lumjs/core/arrays.add.after
- */
-function after(array, oldValue, newValue, ifMissing=-1)
-{
-  return _addWith(array, oldValue, newValue, ifMissing, append);
-}
-
-/**
- * Insert a value to an array using special logic.
- * 
- * See the `pos` argument for the positioning logic used.
- * 
- * @param {Array} array - Array to add the value to.
- * @param {*}     value - Value to add to the array.
- * @param {number} [pos=-1] Position to insert at.
- * 
- * If `pos` is less than `0` this uses `append()`;
- * Otherwise it uses `prepend()`.
- *
- * @returns {Array} `array`
- * @alias module:@lumjs/core/arrays.add.insert
- */
-function insert(array, value, pos=-1)
-{
-  if (pos < 0)
-  {
-    return append(array, value, pos);
-  }
-  else
-  {
-    return prepend(array, value, pos);
-  }
-}
-
-/**
- * A wrapper class to provide helper methods to Arrays.
- * 
- * Provides wrapped versions of `prepend()`, `append()`, 
- * `before()`, `after()`, and `insert()`.
- * 
- * The methods obviously pass the array argument, so remove it from
- * the argument signature when using the wrapper method. Other than that,
- * the rest of the arguments are the same as the wrapped functions.
- * 
- * @alias module:@lumjs/core/arrays.add.At
- */
-class ArrayAt
-{
-  /**
-   * Build a wrapper around an array.
-   * 
-   * @param {Array} array - Array to wrap.
-   */
-  constructor(array)
-  {
-    this.array = array;
-  }
-
-  /**
-   * Add wrappers for the helper functions to the Array directly.
-   * 
-   * WARNING: This is monkey patching the array object instance.
-   * If you're okay with that, cool. 
-   * 
-   * Otherwise, use a new `ArrayAt` object instance instead.
-   * 
-   * @param {Array} array - Array to add methods to.
-   * 
-   * @returns {Array} The input `array`
-   */
-  static extend(array)
-  {
-    for (const methName in ArrayAdd)
-    {
-      const methFunc = ArrayAdd[methName];
-      def(array, methName, methFunc.bind(array, array));
-    }
-    return array;
-  }
-
-  /**
-   * A static method that calls `new ArrayAt(array)`;
-   * 
-   * @param {Array} array - Array to wrap
-   * @returns {module:@lumjs/core/arrays.ArrayAt} A new instance.
-   */
-  static new(array)
-  {
-    return new this(array);
-  }
-
-} // ArrayAt class
-
-// Set up ArrayAt methods, and export the functions.
-for (const methName in ArrayAdd)
-{
-  const methFunc = ArrayAdd[methName];
-
-  def(ArrayAt.prototype, methName, function()
-  {
-    methFunc(this.array, ...arguments);
-  });
-}
-
-def(ArrayAdd, 'At', ArrayAt);

package/lib/arrays/list.js

@@ -1,314 +0,0 @@
-/**
- * A wrapper class to abstract functionality of various kinds of lists.
- *
- * Supports `Array`, `Set`, and `Map` explicitly.
- * Other classes may be supported. YMMV.
- *
- * @alias module:@lumjs/core/arrays.List
- */
-class List
-{
-  /**
-   * A list of known closure properties.
-   *
-   * Corresponding `wrap_${closure}` methods will be used to generate
-   * the closure properties.
-   */
-  static get KNOWN_CLOSURES()
-  {
-    return (Object.getOwnPropertyNames(this.prototype)
-      .filter(name => name.startsWith('wrap_')));
-  }
-
-  /**
-   * Build a new List wrapper.
-   *
-   * @param {object} obj - The list object.
-   *
-   * Typically an `Array`, `Set`, `Map`, or something similar.
-   * Not all of types will support all features. YMMV.
-   *
-   * @param {object} [opts] Options for advanced use.
-   *
-   * @param {bool} [opts.allowRaw=false] Attempt to support raw objects?
-   *
-   * Treat regular Javascript objects as lists, as they are a kind of
-   * map after all. This may lead to unusual results. YMMV.
-   *
-   * @param {mixed} [opts.closures=true] Create closure methods?
-   *
-   * If `true` or `"*"` we will create all known closure properties.
-   *
-   * If an `Array` it's the list of closure names we want to create.
-   * Possible values can be found in `List.KNOWN_CLOSURES`.
-   *
-   * If it's a `string` it's treated as a whitespace separated list
-   * of closure names and split into an `Array`.
-   *
-   * If `false` we won't create any closure properties.
-   *
-   */
-  constructor(obj, opts={})
-  {
-    this.obj = obj;
-    this.opts = opts;
-    this.allowRaw = opts.allowRaw ?? false;
-    this.setupClosures(opts.closures ?? true);  
-  }
-
-  setupClosures(closures)
-  {
-    if (!closures)
-    { // Nothing to do.
-      return;
-    }
-
-    if (closures === true || closures === '*')
-    { // Setup all closures.
-      closures = this.constructor.KNOWN_CLOSURES;
-    }
-    else if (typeof closures === S)
-    {
-      closures = closures.trim().split(/\s+/);
-    }
-    
-    if (Array.isArray(closures))
-    {
-      for (const closure of closures)
-      {
-        const meth = 'wrap_'+closure;
-        if (typeof this[meth] === F)
-        { // Create the detail property.
-          this[closure] = this[meth]();
-        }
-        else
-        {
-          console.error({closure, closures, list: this});
-          throw new Error("Unsupported closure");
-        }
-      }
-    }
-    else
-    {
-      console.error({closures, list: this});
-      throw new TypeError("Invalid closures value");
-    }
-  }
-
-  unsupported(obj, forClosure, info, retVal=false)
-  {
-    console.error("Unsupported object", {obj, forClosure, info, list: this});
-    return () => retVal;
-  }
-
-  /**
-   * Return a closure that returns if an item is in a list object.
-   *
-   * @param {object} obj - The list object the closure will be for.
-   *
-   * May be an `Array`, `Set`, `Map`, or `TypedArray` or any object
-   * that has either an `includes()` or `has()` method.
-   *
-   * @returns {function}
-   * @throws {TypeError}
-   */
-  wrap_contains(obj=this.obj, allowRaw=this.allowRaw)
-  {
-    if (typeof obj.includes === F)
-    { // Array and TypedArray have includes()
-      return item => obj.includes(item);
-    }
-    else if (typeof obj.has === F)
-    { // Set and Map have has()
-      return item => obj.has(item);
-    }
-    else if (allowRaw)
-    { // A fallback to raw object search.
-      return item => (typeof obj[item] !== undefined);
-    }
-    else
-    { // Nope.
-      return this.unsupported(obj, 'contains', {allowRaw});
-    }
-  }
-
-  /**
-   * Return a closure that removes an item from a list.
-   *
-   * @param {object} obj - The list object the closure will be for.
-   *
-   * May be an `Array`, `Set`, `Map`, or anything with a `delete()` method.
-   *
-   * @returns {function}
-   * @throws {TypeError}
-   */
-  wrap_remove(obj=this.obj, allowRaw=this.allowRaw)
-  {
-    let closure;
-    if (Array.isArray(obj))
-    { // Arrays have no easy method to do this.
-      closure = function(item) 
-      {
-        let removed = 0;
-        let index = obj.indexOf(item);
-        while (index !== -1)
-        {
-          obj.splice(index, 1);
-          removed++;
-          index = obj.indexOf(item, index);
-        }
-        return removed;
-      }
-    }
-    else if (typeof obj.delete === F)
-    { // Use the delete() method.
-      closure = item => (obj.delete(item) ?  1 : 0);
-    }
-    else if (allowRaw)
-    { // Fallback to removing the property.
-      closure = function(item)
-      {
-        if (obj[item] === undefined)
-        {
-          return 0;
-        }
-        else
-        {
-          return (delete obj[item] ? 1 : 0);
-        }
-      }
-    }
-    else
-    { // Nada.
-      closure = this.unsupported(obj, 'remove', {allowRaw}, 0);
-    }
-    return closure;
-  }
-
-  /** 
-   * See if our list object contains *any* of the specified items.
-   *
-   * @param  {...any} items 
-   * @returns {boolean}
-   */
-  containsAny(...items)
-  {
-    for (const item of items)
-    {
-      if (this.contains(item))
-      { // Item found.
-        return true;
-      }
-    }
- 
-    // No items found.
-    return false;
-  }
-
-  /**
-    * See if our list contains *all* of the specified items.
-    *
-    * @param  {...any} items 
-    * @returns {boolean}
-    */
-  containsAll(...items)
-  {
-    for (const item of items)
-    {
-      if (!this.contains(item))
-      { // An item was missing.
-        return false;
-      }
-    }
-    // All items found.
-    return true;
-  }
-
-  /**
-   * Remove items from our list object.
-   * 
-   * Passed any number of items, it will see if any of those items are
-   * found in the array, and if they are, will remove them from the array.
-   * 
-   * @param  {...any} items 
-   * @returns {number} Number of items actually removed.
-   */
-  removeAll(...items)
-  {
-    let removed = 0;
-    for (const item of items)
-    {
-      removed += this.remove(item);
-    }
-    return removed;
-  }
-
-  /**
-   * Return a List instance for the passed object.
-   *
-   * If the object is already a `List` it is returned as is.
-   *
-   * @param {object} obj - The list object.
-   * @param {object} [opts] - Passed to constructor.
-   */
-  static for(obj, opts)
-  {
-    return (obj instanceof this) ? obj : new this(obj, opts);
-  }
-}
-
-const CONTAINS_OPTS = {closures: ['contains']};
-
-/** 
- * See if an list object contains *any* of the specified items.
- *
- * @param {object} list - A `List` or object for `new List(list)`;
- * @param  {...any} items 
- * @returns {boolean}
- * @alias module:@lumjs/core/arrays.containsAny
- */
-function containsAny(list, ...items)
-{
-  return List.for(list, CONTAINS_OPTS).containsAny(...items);
-}
-
-List.containsAny = containsAny;
-
- /**
-  * See if a list contains *all* of the specified items.
-  *
-  * @param {object} list - A `List` or object for `new List(list)`;
-  * @param  {...any} items 
-  * @returns {boolean}
-  * @alias module:@lumjs/core/arrays.containsAll
-  */
-function containsAll(list, ...items)
-{
-  return List.for(list, CONTAINS_OPTS).containsAll(...items);
-}
-
-List.containsAll = containsAll;
-
-const REMOVE_OPTS = {closures: ['remove']};
-
-/**
- * Remove items from a list object.
- * 
- * Passed any number of items, it will see if any of those items are
- * found in the array, and if they are, will remove them from the array.
- * 
- * @param {object} list - A `List` or object for `new List(list)`; 
- * @param  {...any} items 
- * @returns {number} Number of items actually removed.
- * @alias module:@lumjs/core/arrays.removeItems
- */
-function removeItems(list, ...items)
-{
-  return List.for(list, REMOVE_OPTS).removeAll(...items);
-}
-
-List.removeItems = removeItems;
-
-module.exports = exports = List;
-
-const {F,S} = require('../types');

package/lib/arrays/typed.js

@@ -1,139 +0,0 @@
-'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}