@lumjs/core 1.23.0 → 1.24.0

package/TODO.md

@@ -1,6 +1,35 @@
 # TODO
 
-- Proper tests using new [@lumjs/tests](https://github.com/supernovus/lum.tests.js) library.
+## v2.x
+
+I'm thinking it's getting close to time to do a big cleanup of the codebase,
+and refactor a few things that have gotten rather crufty. While there may be
+a few more releases in the `1.x` series, I think focusing on a clean break
+for the future would be a good idea. A few of the things I want to do:
+
+- Remove all deprecated code:
+  - `obj.{copyAll,duplicateOne,duplicateAll}`
+  - `types.instanceOf` and related options in `types.isa`
+  - `<meta>.AbstractClass`
+- Implement a new `obj.copy` API function/class
+  - Will completely replace `obj.{clone,copyProps,mergeNested}`
+  - Offer an extended version of the declarative API from `copyProps`
+  - Cut anything that seems superfluous or rarely used
+  - Add ability to copy `Symbol` properties
+- Replace `obj.syncNested` with `obj.sync` using the new `obj.copy` API
+
+I will likely update this list a bit before I get around to starting the
+new branch that will eventually become the `2.0.0` release.
+
+I also want to make a new version of the [@lumjs/compat] package that
+will be more helpful for major updates in the future, so it will have
+a corresponding `v2.x` release at the same time as this package.
+
+## Tests
+
+Write proper tests using [@lumjs/tests] library.
+This list of files is out of date and needs updating.
+
   - [x] `types/js`
   - [x] `types/basics` 
   - [x] `types/root`
@@ -29,3 +58,17 @@
   - [ ] `observable`
   - [ ] `index`
 
+Would be nice to have the tests finished for the planned `2.x` release.
+
+## Documentation
+
+Go through all the DocBlocks and ensure the documentation is up-to-date and
+good enough to actually be useful.
+
+This would also be nice to have finished for the planned `2.x` release.
+
+---
+
+[@lumjs/tests]: https://github.com/supernovus/lum.tests.js 
+[@lumjs/compat]: https://github.com/supernovus/lum.compat.js
+

package/lib/maps.js

@@ -2,7 +2,7 @@
  * Map object helper functions.
  * @module @lumjs/core/maps
  */
-const {F,isObj} = require('./types/js');
+const {F,S,SY,isObj,def,isComplex} = require('./types/js');
 
 /**
  * Build a `Map` instance out of various types of objects.
@@ -61,7 +61,119 @@ function mapOf(input)
   return map;
 }
 
+/**
+ * Get a `Map` stored inside any `object` or `function` target,
+ * using a `Symbol` property for more protected/private storage.
+ * 
+ * It will build the `Map` the first time this is called on a given target;
+ * then it will use the existing instance for any subsequent calls.
+ * 
+ * @alias module:@lumjs/core/maps.getSymbolMap
+ * 
+ * @param {(object|function)} target - The target for the Map storage.
+ * 
+ * A Symbol property with a new Map instance will be added to the `target` 
+ * the first time this function is called. 
+ * 
+ * Then every subsequent call with the same `target` and `symbol` will 
+ * return the Map instance stored in the Symbol property.
+ * 
+ * @param {(Symbol|string)}   symbol - Symbol used to store the Map.
+ * 
+ * If this is a `string`, it will be passed to `Symbol.for()` to get
+ * a globally registered Symbol to use for the Map storage property.
+ * 
+ * If you don't want a globally registerd Symbol, simply use `Symbol(name)`
+ * in your own class and pass the Symbol itself instead of a string.
+ * 
+ * @returns {Map}
+ * 
+ * @throws {TypeError} If any of the parameters are invalid.
+ */
+function getSymbolMap(target, symbol)
+{
+  if (typeof symbol === S)
+  { // Use a global symbol.
+    symbol = Symbol.for(symbol);
+  }
+  else if (typeof symbol !== SY)
+  {
+    console.error({symbol});
+    throw new TypeError("Invalid symbol");
+  }
+
+  if (!isComplex(target))
+  {
+    console.error({target});
+    throw new TypeError("Invalid target object or function");
+  }
+
+  if (target[symbol] === undefined)
+  { // Have not created the Map yet.
+    def(target, symbol, new Map());
+  }
+
+  return target[symbol];
+}
+
+exports.getSymbolMap = getSymbolMap;
+
+/**
+ * A Key-Value Cache using a _Symbol Map_ for storage.
+ * 
+ * See {@link module:@lumjs/core/maps.getSymbolMap getSymbolMap()} 
+ * for the more information about Symbol Map storage and usage.
+ * 
+ * @alias module:@lumjs/core/maps.getSymbolCache
+ * 
+ * @param {(object|function)} target - For `getSymbolMap()`
+ * @param {(Symbol|string)}   symbol - For `getSymbolMap()`
+ * 
+ * @param {mixed} key - The key you want from the cache.
+ * 
+ * If the `key` exists in the cache, and `reset` is `false`,
+ * then the value will be returned from the cache.
+ * 
+ * @param {function} generator - A value generator function.
+ * 
+ * If the `key` was not found in the cache, or `reset` is `true`,
+ * this function must return the value to be cached and returned.
+ * 
+ * The generator function is called directly, with no `this` assignment,
+ * and no arguments. Just `value = generator()`; nothing else!
+ * 
+ * @param {boolean} [reset=false] Reset the value using the `generator`?
+ * 
+ * Set this to `true` to force the value to be reset/regenerated,
+ * regardless as to if it was already cached or not.
+ * 
+ * This is the only optional parameter; default is `false`.
+ * 
+ * @returns {mixed} The cached value, or the value returned by the 
+ * `generator` function, depending on cache state and the `reset` value.
+ * 
+ * @throws {TypeError} If any of the parameters are invalid.
+ */
+function getSymbolCache(obj, symbol, key, generator, reset=false)
+{
+  const cache = getSymbolMap(obj, symbol);
+  if (!reset && cache.has(key))
+  { // Existing value found.
+    return cache.get(key);
+  }
+
+  if (typeof generator !== F)
+  {
+    throw new TypeError("Invalid generator function");
+  }
+
+  // Get/generate the value, cache it, and return it.
+  const value = generator();
+  cache.set(key, value);
+  return value;
+}
+
 module.exports =
 {
-  mapOf,
+  mapOf, getSymbolMap, getSymbolCache,
 }

package/lib/obj/copyall.js

@@ -7,6 +7,7 @@
  * Use `copyProps`, or `mergeNested` for more robust versions.
  * 
  * @alias module:@lumjs/core/obj.copyAll
+ * @deprecated Use `Object.assign()` instead.
  */
 function copyAll(target, ...sources)
 {
@@ -22,7 +23,7 @@ function copyAll(target, ...sources)
 exports.copyAll = copyAll;
 
 /**
- * Make a copy of a single object using `copyAll`.
+ * Make a (shallow) copy of a single object using `copyAll`.
  * 
  * Use `clone` for a more robust version.
  * 
@@ -31,6 +32,7 @@ exports.copyAll = copyAll;
  * @alias module:@lumjs/core/obj.duplicateOne
  * @param {object} obj - The object to duplicate.
  * @returns {object} A clone of the object.
+ * @deprecated Use `clone()` or `Object.assign()` depending on needs.
  */
 exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
 
@@ -44,5 +46,6 @@ exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
  * @alias module:@lumjs/core/obj.duplicateOne
  * @param {object} obj - The object to duplicate.
  * @returns {object} A clone of the object.
+ * @deprecated Use `Object.assign()`
  */
 exports.duplicateAll = copyAll.duplicate = () => copyAll({}, ...arguments);

package/lib/types/isa.js

@@ -69,38 +69,38 @@ exports.isType = isType;
 const DEFAULT_ISA_PARSER = function(type, v)
 { // `this` is the options object itself.
   if (typeof type.is === F)
-  { // We assume `is()` methods are the type check.
+  { // A simple custom type test.
     if (type.is(v)) return true;
   }
 
   if (typeof type.isa === O)
-  { // Process our known options.
-    const opts = type.isa;
+  { // Process our known rules.
+    const rules = type.isa;
 
-    if (typeof opts.process === F)
+    if (typeof rules.process === F)
     { // Run a method to extend the options further.
-      opts.process(this, v, type);
+      rules.process(this, v, type);
     }
 
-    if (typeof opts.parsers === F)
-    { // Assign another parser.
-      this.parsers.push(opts.parsers);
+    if (typeof rules.parsers === F)
+    { // Add another parser.
+      this.parsers.push(rules.parsers);
     }
 
-    if (typeof opts.test === F)
-    { // A custom test, will be passed `v` and the current `opts`.
-      if (opts.test(v, this))
+    if (typeof rules.test === F)
+    { // A more advanced custom type test.
+      if (rules.test(v, this, type))
       { // Mark this as having passed.
         return true;
       }
     }
 
-    // Okay, now anything else gets set.
+    // Okay, now anything else gets set as an option.
     const RESERVED = ['parsers','process','test'];
-    for (const opt in opts)
+    for (const opt in rules)
     {
       if (RESERVED.includes(opt)) continue; // Skip it.
-      this[opt] = opts[opt];
+      this[opt] = rules[opt];
     }
 
   }
@@ -131,27 +131,22 @@ function processOptions(type, v)
  * @param {*} v - The value we're testing.
  * @param {...any} types - The types the value should be one of.
  * 
- * For each of the `types`, by default if it is a `string` 
- * we test with `isType()`, if it is a `function` we see if `v`
- * is either an instance of the type or a sub-class of it.
+ * Each of the `type` tests in `types` may be one of:
  * 
- * If it is an `object` and has an `is()` method, use that as the test.
- * 
- * If it is an `object` it will be passed to the current options parsers.
- * The default options parser looks for an `object` property called `isa`,
- * which supports the following child properties:
- * 
- *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
- *  - `parsers: function`, Add another options parser function.
- *  - `process: function`, A one-time set-up function.
- *  - `test: function`, Pass the `v` to this and return `true` if it passes.
- *  - `instanceof: boolean`, If `true` use `instanceof` *instead of* `isInstance()`.
- *     As of version `1.22`, this defaults to `true`.
- *  - Anything else will be set as an option that may be used by other parsers.
+ * - `string` → Use `isType()` for the test.
+ * - `function` → Assumed to be a class constructor. Will return `true` if:
+ *   - `v` is an an `object` instance of the class.
+ *   - `v` is a `function` that is in the prototype tree of the class.
+ * - `object` → Use `parsers` in {@link module:@lumjs/core/types~IsaOptions}
+ *   to attempt to handle the value. These may define custom tests,
+ *   or be used to set advanced options.
  * 
  * Any other type value will only match if `v === type`
  * 
  * @returns {boolean} Was the value one of the desired types?
+ * 
+ * Will be `true` if _any one_ of the tests pass, or `false` if none passed.
+ * 
  * @alias module:@lumjs/core/types.isa
  */
 function isa(v, ...types)
@@ -159,10 +154,10 @@ function isa(v, ...types)
   // A special options object.
   const opts =
   {
-    needProto: false,
     parsers: [DEFAULT_ISA_PARSER],
     process: processOptions,
     instanceof: true,
+    needProto: false,
   }
 
   for (const type of types)
@@ -206,22 +201,131 @@ function isa(v, ...types)
 exports.isa = isa;
 
 /**
- * Extended return value from any test powered by the `OfTest` class.
+ * Options for the `isa()` function.
  * 
- * Used if `rules.details` was set to `true`.
+ * Only the default options that are supported without using
+ * custom `object` parsers are listed below.
  * 
- * @typedef module:@lumjs/core/types.OfTestResult
+ * @typedef {object} module:@lumjs/core/types~IsaOptions
  * 
- * @prop {boolean} pass  - Did the test pass?
- * @prop {boolean} empty - Was the list empty?
+ * @prop {module:@lumjs/core/types~IsaParser[]} parsers - Object parsers
  * 
- * @prop {object} [failed] Failure information;
- * Only addedd if `pass` is `false`.
+ * These parser functions will be used to handle `object` _type_ values
+ * passed to the `isa()` function. The objects can be used to specify
+ * custom tests, to modify any of the currently set options, or to
+ * extend the functionality of the `isa()` function.
  * 
- * Will be the {@link module:@lumjs/core/types.OfTest.state.at}
- * property from the underlying `OfTest` instance.
- * See the documentation for that property for further details.
+ * There is one _default_ parser which supports two kinds of objects:
+ * 
+ * - {@link module:@lumjs/core/types~IsaTest} → Custom type test.
+ * - {@link module:@lumjs/core/types~IsaRule} → Custom rules to apply.
+ *   Using a rule object is the default way to set options, and the
+ *   only supported way to add new parsers.
+ * 
+ * @prop {function} process - Private/internal method to call parsers
+ * 
+ * Not meant for external use, this is the method which calls all the
+ * current `parsers` whenever an `object` value is passed as a _type_.
+ * It uses the same arguments as the parsers themselves.
+ * 
+ * @prop {boolean} instanceof - Use `instanceof` instead of `isInstance()`
+ * 
+ * As the `isInstance()` function is DEPRECATED, so is this option.
+ * Default: `true` since `v1.22` (was `false` prior to that.)
+ * 
+ * @prop {boolean} needProto - `needProto` argument for `isInstance()`
+ * 
+ * Obviously only applicable if `instanceof` option is `false`.
+ * As the `isInstance()` function is DEPRECATED, so is this option.
+ * Default: `false`
+ * 
+ */
+
+/**
+ * `object` parsers for the `isa()` function.
+ * 
+ * May be used to support more types of `object` type
+ * values passed to the `isa()` function.
+ * 
+ * @callback module:@lumjs/core/types~IsaParser
+ * @param {object} type - The type value passed to `isa()`
+ * @param {mixed} v - The value being tested by `isa()`
+ * @this {module:@lumjs/core/types~IsaOptions}
+ */
+
+/**
+ * A simple custom `isa()` type test supported by the default parser.
+ * 
+ * @typedef {object} module:@lumjs/core/types~IsaTest
+ * @prop {function} is - The test function to run.
+ * 
+ * Will be passed the value being tested as the only argument.
+ * 
+ * If this returns a value that evaluates to `true`, then the
+ * test has passed, and `isa()` will immediately return `true`.
+ * 
+ * If this returns a value that evaluates to `false`, then the test
+ * has failed, and `isa()` will move onto the next type test,
+ * continuing until either one of the tests passes, or all fail.
+ *
+ */
+
+/**
+ * Rule definition `object` supported by the default `isa()` parser.
  * 
+ * @typedef {object} module:@lumjs/core/types~IsaRule
+ * @prop {module:@lumjs/core/types~IsaRules} isa - The rules to apply.
+ */
+
+/**
+ * Supported properties for `isa()` Rules.
+ * 
+ * Any property not _explicitly_ listed in this description will set
+ * the {@link module:@lumjs/core/types~IsaOptions option} of that name
+ * to the specified value. This can be used to set both default options,
+ * or any custom options supported by extra parsers you may add.
+ * 
+ * @typedef {object} module:@lumjs/core/types~IsaRules
+ * 
+ * @prop {module:@lumjs/core/types~IsaParser} [parsers] Add a parser.
+ * 
+ * This rule will append the parser function to the array of `parsers`
+ * in the options for the current `isa()` function call.
+ * 
+ * @prop {module:@lumjs/core/types~IsaRuleTest} [test] A type test function.
+ * @prop {module:@lumjs/core/types~IsaRuleProcess} [process] A setup function.
+ * 
+ * @see {@link module:@lumjs/core/types~IsaRule}
+ */
+
+/**
+ * An advanced custom `isa()` test declared in a Rule.
+ * 
+ * @callback module:@lumjs/core/types~IsaRuleTest
+ * 
+ * @param {mixed} v - The value being tested by `isa()`
+ * @param {module:@lumjs/core/types~IsaOptions} opts - `isa()` options
+ * @param {object} type - The type value passed to `isa()`
+ * @this {module:@lumjs/core/types~IsaRules}
+ * @returns {boolean} The return values from this are handled the same way
+ * as the `is()` method of {@link module:@lumjs/core/types~IsaTest} objects.
+ * 
+ */
+
+/**
+ * A custom `isa()` Rule setup function.
+ * 
+ * Can be used to customize the options in ways not normally
+ * allowed, or do any other setup logic that is beyond the
+ * capabilities of the default options parser.
+ * 
+ * @callback module:@lumjs/core/types~IsaRuleProcess
+ * 
+ * @param {module:@lumjs/core/types~IsaOptions} opts - Options
+ * @param {mixed} v - The value being tested.
+ * @param {object} type - The type value passed to `isa()`.
+ * @this {module:@lumjs/core/types~IsaRules}
+ * @returns {void}
  */
 
 /**
@@ -468,6 +572,25 @@ class OfTest
 
 exports.OfTest = OfTest;
 
+/**
+ * Extended return value from any test powered by the `OfTest` class.
+ * 
+ * Used if `rules.details` was set to `true`.
+ * 
+ * @typedef module:@lumjs/core/types.OfTestResult
+ * 
+ * @prop {boolean} pass  - Did the test pass?
+ * @prop {boolean} empty - Was the list empty?
+ * 
+ * @prop {object} [failed] Failure information;
+ * Only addedd if `pass` is `false`.
+ * 
+ * Will be the {@link module:@lumjs/core/types.OfTest.state.at}
+ * property from the underlying `OfTest` instance.
+ * See the documentation for that property for further details.
+ * 
+ */
+
 /**
  * A nested class representing an explicit set of rules for `OfTest`.
  * 

package/lib/types/root.js

@@ -1,5 +1,6 @@
 const {U} = require('./js');
 const {isNil,isArray} = require('./basics');
+const removeFromArray = require('../arrays/list').removeItems;
 
 // «private»
 function no_root()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "main": "lib/index.js",
   "exports":
   {

package/PLANS.txt

@@ -1,10 +0,0 @@
-# Future Plans
-
-## 2.x 
-
-I've done a lot of updates to this vanity library since writing it, and it's built up a 
-bit of cruft over time.
-
-While it likely won't happen for a while yet, I do plan to have a clean-up version where
-anything marked deprecated is removed, and any other cleanup that may break stuff can be
-done at that time as well.