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

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

@@ -0,0 +1,168 @@
+const def = require('./def');
+const {O, F, S, B, N, U, SY, BI} = require('./js');
+const 
+{
+  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+  isArguments, isProperty, doesDescriptor,
+} = require('./basics');
+
+/**
+ * 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
+ * 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', {})
+   ('keys',
+   {
+     get()
+     {
+       return Object.keys(this);
+     }
+   })
+   ('list', 
+   {
+     get() 
+     {
+       return Object.values(this);
+     }
+   })
+   ('add', function(name, ident, test, exportTest)
+   {
+     if (isObj(name))
+     { // A shortcut for adding multiple items.
+       for (let key in name)
+       {
+         const val = name[key];
+         if (typeof val === S)
+         { // It's a 'name': 'ident' mapping.
+           TYPES.add(key, val);
+         }
+         else if (typeof val === F)
+         { // It's a 'name': test() mapping.
+           TYPES.add(key, null, val);
+         }
+         else if (isObj(val))
+         { // An object, can have 'id', 'test', and 'export' properties.
+           TYPES.add(key, val.id, val.test, val.export);
+         }
+         else 
+         { // Unsupported.
+           throw new TypeError("Invalid add type property");
+         }
+       }
+     }
+     else if (typeof name === S)
+     { 
+       if (typeof ident !== S)
+       { // Use a lowercase version of the name.
+         ident = name.toLowerCase();
+       }
+       // And just to be sure.
+       name = name.toUpperCase();
+       dt(name, {enumerable: true, value: ident});
+       if (typeof test === F)
+       { // A custom test, mapped to the ident.
+         def(TYPES.tests, ident, test);
+         if (typeof exportTest === S && isObj(TYPES.$module))
+         { // So extensions can add new type tests.
+           TYPES.$module.exports[exportTest] = test;
+         }
+       }
+     }
+     else 
+     {
+       throw new TypeError("Invalid arguments");
+     }
+   });
+ 
+ // Now we'll actually set up the built-in TYPES.
+ TYPES.add(
+ {
+   // First the simplest ones that just use `typeof`.
+   F, S, B, N, U, SY, BI,
+   // Next the custom object test, overriding `typeof`.
+   O: {id: O, test: isObj},
+   // Custom type defs that never had typeof tests.
+   NULL: v => (v === null),
+   ARGS: {id: 'arguments', test: isArguments},
+   PROP: {id: 'property',  test: isProperty},
+   ARRAY: isArray,
+   TYPEDARRAY: isTypedArray,
+   DESCRIPTOR: doesDescriptor,
+   COMPLEX: isComplex,
+   SCALAR: isScalar,
+   NIL: isNil,
+   NOTNIL: notNil,
+   MAP: v => v instanceof Map,
+ });
+ 
+ module.exports = TYPES;
+ 

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "@lumjs/core",
-  "version": "1.0.0-beta.1",
-  "main": "index.js",
+  "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,6 +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",
+    "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/test/arrays.js

@@ -0,0 +1,19 @@
+// Current test count.
+const plan = 5;
+// A new test instance.
+const t = require('@lumjs/tests').new({module, plan});
+// The arrays core module
+const arr = require('../lib/arrays');
+
+t.ok(arr.containsAny(['hello','world'], 'world'), 'containsAny([a], a)');
+t.ok(!arr.containsAny(['hello','world'], 'universe'), '!containsAny([a], b)');
+t.ok(arr.containsAll(['hello','darkness','my','old','friend'], 'hello', 'friend'), 'containsAll([a,b,c], a, c)');
+t.ok(!arr.containsAll(['nothing','to','see'], 'nothing', 'here'), '!containsAll([a,b,c], a, d)');
+
+const a1 = ['hello', 'darkness', 'my', 'old', 'friend'];
+arr.removeItems(a1, 'darkness');
+t.isJSON(a1, ['hello','my','old','friend'], 'removeFromArray(...)');
+
+// All done.
+t.output();
+

package/test/meta.js

@@ -0,0 +1,17 @@
+// Current test count.
+const plan = 1;
+// A new test instance.
+const t = require('@lumjs/tests').new({module, plan});
+// The meta core module
+const meta = require('../lib/meta');
+
+t.dies(()=>meta.NYI(), 'NYI()');
+
+// TODO:
+// - stacktrace()
+// - AbstractClass
+// - Functions.*
+
+// All done.
+t.output();
+

package/test/types.js

@@ -1,20 +1,14 @@
 // Current test count.
-const plan = 91;
+const plan = 120;
 // A new test instance.
 const t = require('@lumjs/tests').new({module, plan});
 // The types core module
-const types = require('../index').types;
+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(
@@ -151,15 +151,6 @@ testIsType(
   [TYP.PROP, null],
 ], true);
 
-t.ok(types.containsAny(['hello','world'], 'world'), 'containsAny([a], a)');
-t.ok(!types.containsAny(['hello','world'], 'universe'), '!containsAny([a], b)');
-t.ok(types.containsAll(['hello','darkness','my','old','friend'], 'hello', 'friend'), 'containsAll([a,b,c], a, c)');
-t.ok(!types.containsAll(['nothing','to','see'], 'nothing', 'here'), '!containsAll([a,b,c], a, d)');
-
-const arr = ['hello', 'darkness', 'my', 'old', 'friend'];
-types.removeFromArray(arr, 'darkness');
-t.isJSON(arr, ['hello','my','old','friend'], 'removeFromArray(...)');
-
 (function(){ t.ok(types.unbound(this), 'unbound(unboundThis)'); })();
 (function(){ t.ok(!types.unbound(this), '!unbound(boundThis)') }).bind({})();
 typesInstance.notUnbound();
@@ -170,15 +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');
+  
+  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})')
 }
 
-t.dies(()=>types.NYI(), 'NYI()');
+// TODO: isa() and needs()
+// TODO: stringify()
 
 // All done.
 t.output();

package/index.js

@@ -1,64 +0,0 @@
-// The core library is made up of a bunch of child modules,
-// as well as some standalone classes and functions.
-
-/**
- * Constants and functions for basic type checking.
- * @namespace types
- */
-const types = require('./src/types');
-const def = types.def;
-
-/**
- * Information about the JS context we're running in.
- * @namespace context
- */
-const context = require('./src/context');
-
-/**
- * Functions for working with strings and locales.
- * @namespace strings
- */
-const strings = require('./src/strings');
-
-/**
- * Functions for working with binary flags.
- * @namespace flags
- */
-const flags = require('./src/flags');
-
-/**
- * Functions and Enums for working with Descriptors.
- * @namespace descriptors
- */
-const descriptors = require('./src/descriptors');
-// The *primary* export from descriptors is DESC.
-const DESC = descriptors.DESC;
-
-/**
- * Functions for manipulating objects.
- * @namespace obj
- */
-const obj = require('./src/obj');
-
-/**
- * Function for getting values and properties with fallback defaults.
- * @namespace opt
- */
-const opt = require('./src/opt');
-
-// A few modules that we're going to expand into the main exports. 
-const {randomNumber, InternalObjectId} = require('./src/objectid');
-const {stacktrace,AbstractClass,Functions} = require('./src/meta');
-
-// And finally some standalone functions.
-const Enum = require('./src/enum');
-const prop = require('./src/prop');
-const lazy = require('./src/lazy');
-const observable = require('./src/observable');
-
-module.exports =
-{
-  types, context, strings, flags, descriptors, obj, opt,
-  randomNumber, InternalObjectId, Enum, prop, lazy, observable,
-  stacktrace, AbstractClass, Functions, def, DESC,
-}

package/src/context.js

@@ -1,47 +0,0 @@
-
-const {root,B,F,U,O,isObj,def} = require('./types');
-
-/**
- * Context object.
- * 
- * @namespace Lum.context
- * 
- * Offers some insight into the current JS context.
- * 
- */
-
-const ctx = {root};
-
-const rootHas = what => typeof root[what] !== U;
-const cd = def(ctx, true);
-
-cd('AMD', typeof define === F && define.amd)
-  ('hasExports', typeof exports !== U)
-  ('hasModule', typeof module === O && module !== null)
-  ('CJS', ctx.hasModule && isObj(module.exports))
-  ('isWindow', !ctx.CJS && rootHas('window'))
-  ('isWorker', !ctx.CJS && rootHas('WorkerGlobalScope'))
-  ('isServiceWorker', !ctx.CJS && rootHas('ServiceWorkerGlobalScope'))
-  ('isDedicatedWorker', !ctx.CJS && rootHas('DedicatedWorkerGlobalScope'))
-  ('isSharedWorker', !ctx.CJS && rootHas('SharedWorkerGlobalScope'))
-  ('isBrowser', ctx.isWindow || ctx.isWorker);
-
-// Does the global object/property exist?
-// Caches the results so we can do `context.has.Thingy` tests.
-function hasRoot(ns)
-{
-  if (typeof hasRoot[ns] === B) return hasRoot[ns];
-  const result = rootHas(ns);
-  def(hasRoot, ns, {value: result, enumerable: true});
-  return result;
-}
-
-// Build some common has items.
-for (const what of ['Proxy','Promise','Reflect','fetch'])
-{
-  hasRoot(what);
-}
-
-cd('has', hasRoot);
-
-module.exports = ctx;