@lumjs/core 1.0.0-beta.4 → 1.0.0-beta.6

package/lib/types/index.js

@@ -1,4 +1,20 @@
-/// Type checking and other features common to everything else.
+/**
+ * Fundamental Types sub-module.
+ * 
+ * As `@lumjs/core` is the foundation for all my JS libraries,
+ * this sub-module is the foundation for `@lumjs/core`.
+ * Everything else is built upon this.
+ * 
+ * @module @lumjs/core/types
+ * @property {string} O - "object"
+ * @property {string} F - "function"
+ * @property {string} S - "string"
+ * @property {string} B - "binary"
+ * @property {string} N - "number"
+ * @property {string} U - "undefined"
+ * @property {string} SY - "symbol"
+ * @property {string} BI - "bigint"
+ */
 
 // Constants representing core Javascript types.
 const {O, F, S, B, N, U, SY, BI} = require('./js');
@@ -23,6 +39,7 @@ const {needObj, needType, needs} = require('./needs');
 
 const def   = require('./def');
 const TYPES = require('./typelist');
+const stringify = require('./stringify');
 
 // Okay, add all those to our exports.
 // Further tests can be added by `TYPES.add()` later.
@@ -31,7 +48,7 @@ module.exports =
   O, F, S, B, N, U, SY, BI, TYPES, root, unbound, def,
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
-  isInstance, isType, isa, needObj, needType, needs,
+  isInstance, isType, isa, needObj, needType, needs, stringify,
 }
 
 // Last but not least, this will be the module for TYPES.add()

package/lib/types/isa.js

@@ -8,6 +8,7 @@ const TYPES = require('./typelist');
  * @param {function} f - The constructor/class we want.
  * @param {boolean} [needProto=false] If true, the `v` must have a `prototype`.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isInstance
  */
  function isInstance(v, f, needProto=false) 
  {
@@ -30,24 +31,15 @@ const TYPES = require('./typelist');
   * 
   * @param {string} type - The type we're checking for.
   * 
-  * This supports all the same type names as `typeof` plus:
-  * 
-  * - `arguments`   → An arguments object inside a function.
-  * - `array`       → An Array object.
-  * - `null`        → A null value.
-  * - `typedarray`  → One of the typed array objects.
-  * - `descriptor`  → An object which is a valid descriptor.
-  * - `complex`     → Either an `object` or a `function.
-  * - `scalar`      → Anything other than an `object` or `function`.
-  * - `property`    → A `string` or a `symbol`.
-  * - `nil`         → Either `null` or `undefined`.
+  * This supports all the same type names as `typeof` plus any of
+  * the properties defined in the `TYPES` object.
   * 
   * One other thing, while `typeof` reports `null` as being an `object`,
   * this function does not count `null` as a valid `object`. 
   * 
   * @param {*} v - The value we're testing. 
-  * 
   * @returns {boolean} If the value was of the desired type.
+  * @alias module:@lumjs/core/types.isType
   */
  function isType(type, v)
  {
@@ -138,6 +130,7 @@ const TYPES = require('./typelist');
   * Any other type value will only match if `v === type`
   * 
   * @returns {boolean} Was the value one of the desired types?
+  * @alias module:@lumjs/core/types.isa
   */
  function isa(v, ...types)
  {

package/lib/types/needs.js

@@ -9,6 +9,7 @@ const {isObj, isComplex} = require('./basics');
  * @param {boolean} [allowFunc=false] - Also accept functions?
  * @param {string} [msg] A custom error message.
  * @throws {TypeError} If the type check failed.
+ * @alias module:@lumjs/core/types.needObj
  */
 function needObj (v, allowFunc=false, msg=null)
 {
@@ -33,6 +34,7 @@ exports.needObj = needObj;
  * @param {*} v - The value we're testing.
  * @param {string} [msg] A custom error message.
  * @throws {TypeError} If the type check failed.
+ * @alias module:@lumjs/core/types.needType
  */
 function needType (type, v, msg, unused)
 {
@@ -77,7 +79,10 @@ const NEEDS_PARSER = function(type, v)
 * look for an `object` with a single property named `error`
 * which can be either a `string` or any subclass of `Error`.
 * If specified, it will override the error message that will be thrown.
-* 
+*
+* @throws {TypeError} If the type check failed.
+* @throws {Error} If a custom error was specified.
+* @alias module:@lumjs/core/types.needs
 */
 function needs(v, ...types)
 {

package/lib/types/root.js

@@ -9,6 +9,7 @@ function no_root()
 
 /**
  * The global root object. Usually `globalThis` these days.
+ * @alias module:@lumjs/core/types.root
  */
 const root = typeof globalThis !== U ? globalThis
   : typeof global !== U ? global 
@@ -32,6 +33,7 @@ const unboundObjects = [];
  *   If the is `true` we use an global list that can register special
  *   internal objects. Otherwise an `Array` of unbound objects may be used.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.unbound
  */
 function unbound(whatIsThis, rootIsUnbound=true, areUnbound=false)
 {
@@ -56,13 +58,11 @@ const def = require('./def');
 /**
  * Add an item to the unbound global objects list.
  * 
- * @method unbound.add 
- * 
+ * @function
  * @param {(object|function)} obj - The object to be considered unbound.
- * 
  * @returns {boolean} Will be `false` if `obj` is already unbound.
- * 
  * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
+ * @alias module:@lumjs/core/types.unbound.add
  */
 def(unbound, 'add', function (obj)
 {
@@ -79,13 +79,11 @@ def(unbound, 'add', function (obj)
 /**
  * Remove an item from the unbound global objects list.
  * 
- * @method unbound.remove
- * 
+ * @function
  * @param {(object|function)} obj - The object to be removed.
- * 
  * @returns {boolean} Will be `false` if the item was not in the list.
- * 
  * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
+ * @alias module:@lumjs/core/types.unbound.remove
  */
 def(unbound, 'remove', function(obj)
 {

package/lib/types/stringify.js

@@ -0,0 +1,98 @@
+// Get the extended type list.
+const TYPES = require('./typelist');
+const {isObj, isArray, isTypedArray} = require('./basics');
+
+const TOSTRING = [TYPES.F, TYPES.SY];
+
+/**
+ * Stringify a Javascript value.
+ * 
+ * We typically just use `JSON.stringify()` but that doesn't work on
+ * some types. So this function adds string formats for:
+ *  - `function`
+ *  - `symbol`
+ *  - `TypedArray`
+ *  - `Map`
+ *  - `Set`
+ *  - `Error`
+ * I may add even more extended types in the future, but that's enough
+ * for now.
+ * 
+ * This is NOT meant for serializing data, and does not use a JSON-friendly
+ * output format. I'm writing a different library for that.
+ * 
+ * @param {*} what - The value to stringify.
+ * @param {integer} [recurse=1] Recurse objects to this depth.
+ * @param {boolean} [addNew=false] Use 'new Class()' instead of 'Class()'. 
+ * @returns {string} The stringified value.
+ * @alias module:@lumjs/core/types.stringify
+ */
+function stringify (what, recurse=1, addNew=false)
+{
+  const whatType = typeof what;
+  if (TOSTRING.includes(whatType)) return what.toString();
+
+  // A few formatting helpers used below.
+
+  const classname = () => (addNew ? 'new ' : '') + what.constructor.name;
+  const construct = val => `${classname()}(${val})`;
+  const reconstruct = val => construct(stringify(val,recurse,addNew));
+  const arrayish = vals => reconstruct(Array.from(vals));
+
+  if (isTypedArray(what))
+  { // This one is pretty simple.
+    return construct(what.toString());
+  }
+  
+  if (what instanceof Map)
+  {
+    return arrayish(what.entries());
+  }
+  
+  if (what instanceof Set)
+  {
+    return arrayish(what.values());
+  }
+
+  if (what instanceof Error)
+  {
+    return construct(what.message);
+  }
+  
+  if (recurse && isObj(what))
+  { // Recursion mode enabled.
+    let out = '';
+    if (isArray(what))
+    { // Stringify an array.
+      out = '[';
+      out += what.map(item => stringify(item, recurse-1, addNew)).join(',');
+      out += ']';
+    }
+    else
+    { // Stringify a plain object.
+      out = '{';
+      function add(key, pre='')
+      {
+        out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+      }
+      const keys = Object.keys(what);
+      //console.debug("keys!", keys);
+      if (keys.length > 0)
+      { // Let's add the first key, then all subsequent keys.
+        add(keys.shift());    
+        for (const key of keys)
+        {
+          add(key, ',');
+        }
+      }
+      out += '}';
+    }
+    return out;
+  }
+  else
+  { // If we reached here, there's no special methods, use JSON.
+    return JSON.stringify(what);
+  }
+}
+
+module.exports = stringify;

package/lib/types/typelist.js

@@ -7,12 +7,76 @@ const
 } = require('./basics');
 
 /**
- * A map of type names including special and union types.
+ * A map of **Types**, including *special* and *union* types.
+ * 
+ * Contains the same `O, F, S, B, N, U, SY, BI` properties as also
+ * found in the top-level {@link module:@lumjs/core/types} module.
+ * While most of the core JS types simply use `typeof` as their
+ * test, this maps the `O` (`object`) type to the `isObj` test.
+ * 
  * Will also contain a few helper functions, and a map of tests
- * for any types that require tests other than `typeof v === 'typename'`
+ * that are used by `isType`, `isa`, `needType`, and `needs`.
+ * Any one of these properties may be passed to those functions as
+ * the desired *type* a desired value must be.
+ * 
+ * We will list the types added by the `types` module in
+ * the *Properties* table, and any types added by other *core modules*
+ * in the *Members* list, prior to listing the *Methods*.
+ * 
+ * @namespace module:@lumjs/core/types.TYPES
+ * @property {string} NULL - Represents `null` values.
+ * @property {string} ARGS - Represents an *argument* object.
+ * @property {string} PROP - A `string` or a `symbol`.
+ * @property {string} ARRAY - An `Array` object.
+ * @property {string} TYPEDARRAY - A `TypedArray` object.
+ * @property {string} DESCRIPTOR - A *Descriptor* object (Data or Accessor). 
+ * @property {string} COMPLEX - A `function` or an `object`.
+ * @property {string} SCALAR - A non-null value that is **not** *complex*.
+ * @property {string} NIL - Either `null` or `undefined`.
+ * @property {string} NOTNIL - Anything other than `null` or `undefined`.
+ * @property {string} MAP - A `Map` object.
+ * @property {object} tests - A map of tests for the above types.
  */
  const TYPES = {};
 
+ /**
+  * Add a new type to the `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.add
+  * @function
+  * @param {(string|object)} name - If a `string` the property name to use.
+  *   When adding the property the string will be forced to uppercase.
+  * 
+  *   If an `object` then its a shortcut for adding a bunch of types at once.
+  *   Each key will be the `name`, and the type of the *value* can be one of:
+  *   - `string` → Use as the `ident` parameter.
+  *   - `function` → Use as the `test` parameter.
+  *   - `object` → Supports `id`, `test`, and `export` parameters.
+  * 
+  * @param {?string} [ident] The identifier string for the type.
+  *   If not specified or `null`, it will default to a completely lowercase 
+  *   version of the `name` parameter.
+  * @param {function} [test] A type check test.
+  *   Must accept a single value to test, must return a boolean.
+  * @param {string} [exportTest] A name to export the test as.
+  *   The test will be added to the `types` module with this name.
+  * 
+  * @returns {void}
+  */
+
+ /**
+  * Get a list of type properties available in `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.keys
+  * @function
+  * @returns {string[]}
+  */
+
+  /**
+  * Get a list of type identifier values available in `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.list
+  * @function
+  * @returns {string[]}
+  */
+
  // Let's setup the TYPES with its magic functions.
  const dt = def(TYPES);
  dt('tests', {})

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "@lumjs/core",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "main": "lib/index.js",
+  "exports":
+  {
+    ".": "./lib/index.js",
+    "./types": "./lib/types/index.js",
+    "./arrays": "./lib/arrays.js",
+    "./context": "./lib/context.js",
+    "./strings": "./lib/strings.js",
+    "./flags": "./lib/flags.js",
+    "./obj": "./lib/obj/index.js",
+    "./opt": "./lib/opt.js",
+    "./modules": "./lib/moduless.js",
+    "./meta": "./lib/meta.js",
+    "./enum": "./lib/enum.js",
+    "./observable": "./lib/observable.js",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "repository":
   {
@@ -10,11 +26,13 @@
   },
   "devDependencies":
   {
-    "@lumjs/tests": "^1.0.0"
+    "@lumjs/tests": "^1.0.0",
+    "jsdoc": "^3.6.10"
   },
   "scripts":
   {
     "-TODO-1": "Use `lumtest` once its available",
-    "test": "prove -e node --ext js ./test"
+    "test": "prove -e node --ext js ./test",
+    "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/test/types.js

@@ -1,20 +1,14 @@
 // Current test count.
-const plan = 85;
+const plan = 120;
 // A new test instance.
 const t = require('@lumjs/tests').new({module, plan});
 // The types core module
 const types = require('../lib/types');
 
-// And a quick reference to the type names.
+// A quick reference to the type names.
 const TYP = types.TYPES;
-
-// Helper function.
-function stringify (what)
-{
-  if (typeof what === TYP.F) return what.toString();
-  if (typeof what === TYP.SY) return what.constructor.toString();
-  return JSON.stringify(what);
-}
+// And the stringify function.
+const stringify = types.stringify;
 
 // Now for some further basics.
 t.ok(types.isObj({}), 'isObj({})');
@@ -55,10 +49,16 @@ class SubtypeClass extends TypeClass {}
 const typesInstance = new TypeClass();
 const subtypeInstance = new SubtypeClass();
 
+class DifferentClass {}
+
+const differentInstance = new DifferentClass();
+
 t.ok(types.isInstance(typesInstance, TypeClass), 'isInstance(typeInstance,TypeClass)');
 t.ok(types.isInstance(subtypeInstance, SubtypeClass), 'isInstance(subtypeInstance, SubtypeClass)');
 t.ok(types.isInstance(subtypeInstance, TypeClass), 'isInstance(subtypeInstance, TypeClass)');
-t.ok(!types.isInstance(typesInstance, SubtypeClass), '!isInstance(typeInstance, SubtypeClass');
+t.ok(!types.isInstance(typesInstance, SubtypeClass), '!isInstance(typeInstance, SubtypeClass)');
+t.ok(!types.isInstance(differentInstance, TypeClass), '!isInstance(differentInstance, TypeClass)');
+t.ok(!types.isInstance(typesInstance, DifferentClass), '!isInstance(typesInstance, DifferentClass)');
 
 function doesDesc (tests, not=false)
 {
@@ -126,7 +126,7 @@ testIsType(
   [TYP.SCALAR, true],
   [TYP.SCALAR, 'hi'],
   [TYP.PROP, 'woah'],
-  [TYP.PROP, Symbol('woah'), TYP.PROP+',Symbol'],
+  [TYP.PROP, Symbol('woah')],
 ]);
 
 testIsType(
@@ -161,18 +161,107 @@ t.dies(function(){types.needObj(null); return true}, '!needObj(null)');
 t.ok((function(){types.needType(TYP.S, 'hi'); return true})(), "needType('string','hi')");
 t.dies(function(){types.needType(TYP.O, null); return true}, "!needType('object',null)");
 
+{ // Tests of isa() method.
+  let wants = [TYP.S, TYP.N];
+  t.ok(types.isa('hi', ...wants), 'isa(val, ...types)');
+  t.isa('hello', wants, ' ^ using Test.isa()');
+  t.isa(42, wants, ' ^ with second type');
+  t.ok(!types.isa({}, ...wants), '!isa(val, ...types)');
+  t.nota({}, wants, ' ^ using Test.nota()');
+
+  wants = [SubtypeClass, DifferentClass];
+  t.isa(subtypeInstance, wants, 'isa(val, ...classes)');
+  t.isa(differentInstance, wants, ' ^ with second class');
+  t.nota(typesInstance, wants, 'nota(val, ...classes)');
+
+  wants = [TYP.B, TypeClass];
+  t.isa(true, wants, 'isa() → with mixed types/classes');
+  t.isa(subtypeInstance, wants, ' ^ with second type/class');
+}
+
+{ // Tests of needs() method.
+  let needs = [TYP.S, TYP.N];
+  t.lives(() => types.needs('hi', ...needs), 'needs(val, ...types)');
+  t.lives(() => types.needs(42, ...needs), ' ^ with second type');
+  t.dies(() => types.needs({}, ...needs), ' ^ throws on failure');
+
+  needs = [SubtypeClass, DifferentClass];
+  t.lives(() => types.needs(subtypeInstance, ...needs), 'needs(val, ...classes)');
+  t.lives(() => types.needs(differentInstance, ...needs), ' ^ with second class');
+  t.dies(() => types.needs(typesInstance, ...needs), ' ^ throws on failure');
+
+  needs = [TYP.B, TypeClass];
+  t.lives(() => types.needs(true, ...needs), 'needs() → with mixed types/classes');
+  t.lives(() => types.needs(subtypeInstance, ...needs), ' ^ with second type/class');
+}
+
 { // Try a few versions of 'def'
   const obj = {};
   types.def(obj, 'test1', 'Test 1');
   t.is(obj.test1, 'Test 1', 'def(obj, name, value)');
   types.def(obj)('test2', 'Test 2');
   t.is(obj.test2, 'Test 2', 'def(obj)(name, value)');
+  obj.test2 = '2 Test';
+  t.is(obj.test2, 'Test 2', 'def() is read-only by default');
+
+  types.def(obj, true)('test3', 'Test 3');
+  t.is(Object.keys(obj).length, 1, 'def(obj, true)(...)');
+  
+  types.def(obj, 'a1', function()
+  { // Returning a different property.
+    return this.test2;
+  },
+  function(val)
+  { // Assigning to a different property.
+    this.$$ = val;
+  });
+
+  const gs = 'def(obj, name, getter, setter)';
+  t.is(obj.a1, 'Test 2', gs+'~getter');
+  obj.a1 = 'A1->$$';
+  t.is(obj.$$, 'A1->$$', gs+'~setter');
+
+  types.def(obj, 'test4', 'Test 4', {writable: true});
+  t.is(obj.test4, 'Test 4', 'def(..., {writable}) → added property');
+  obj.test4 = '4 Test';
+  t.is(obj.test4, '4 Test', ' ^ and it was writable');
+
+  const td = types.def(obj);
+  td('getOnly', {get: function() { return 'GETTER'; }});
+  obj.getOnly = 'blah blah blah';
+  t.is(obj.getOnly, 'GETTER', 'def(..., {get: getter}) → getter worked');
+  td('setOnly', {set: function(val) { this.__ = val; }});
+  obj.setOnly = 'SETTER';
+  t.is(obj.__, 'SETTER', 'def(..., {set: setter}) → setter worked');
+  t.is(obj.setOnly, undefined, ' ^ get is undefined');
+
+  td('foobar', {value: 'FOO BAR'});
+  t.is(obj.foobar, 'FOO BAR', 'def(..., {value})');
+
+  let anObj = {value: 'BAR FOO'};
+  td('barfoo', anObj, false);
+  t.is(obj.barfoo, anObj, 'def(..., descriptor, false) → assigned object as value');
   
-  // TODO: new accessor assignment options.
+  td('barfoo2', anObj);
+  t.is(anObj.configurable, true, 'def(..., descriptor) → descriptor is a reference');
+
+  anObj = {value: 'new test'};
+  td('barfoo3', anObj, true);
+
+  t.is(anObj.configurable, undefined, 'def(..., descriptor, true) → cloned descriptor');
+  t.is(obj.barfoo3, 'new test', ' ^ value was correct')
+
+  td(
+  {
+    hello: 'World',
+    goodbye: 'Universe',
+  });
 
+  t.ok((obj.hello === 'World' && obj.goodbye === 'Universe'), 'def(obj, {prop1: value1, prop2: value2})')
 }
 
 // TODO: isa() and needs()
+// TODO: stringify()
 
 // All done.
 t.output();