@lumjs/core 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0-beta.1] - 2022-07-07
+### Added
+- Initial release.
+- Pulled a bunch of the core libraries from the old Lum.js project.
+- Refactored and reorganized the libraries a lot.
+
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.1...HEAD
+[1.0.0-beta.1]: https://github.com/supernovus/lum.core.js/releases/tag/v1.0.0-beta.1
+

package/README.md

@@ -0,0 +1,27 @@
+# lum.core.js
+
+Some small *core* constants, functions, classes, and objects.
+Things that make working with objects in Javascript slightly nicer,
+and work in CommonJS/Node.js and modern browsers without any modifications.
+
+Used by all the rest of my *Lum.js* libraries.
+
+## Exports
+
+TODO: a brief summary of the exports.
+
+## Official URLs
+
+This library can be found in two places:
+
+ * [Github](https://github.com/supernovus/lum.core.js)
+ * [NPM](https://www.npmjs.com/package/@lumjs/core)
+
+## Author
+
+Timothy Totten <2010@totten.ca>
+
+## License
+
+[MIT](https://spdx.org/licenses/MIT.html)
+

package/TODO.md

@@ -0,0 +1,23 @@
+# TODO
+
+- Proper tests using new [@lumjs/tests](https://github.com/supernovus/lum.tests.js) library.
+  - [x] `types`
+  - [ ] `context`
+  - [ ] `strings`
+  - [ ] `flags`
+  - [ ] `descriptors`
+  - [ ] `obj/copyall`
+  - [ ] `obj/copyprops`
+  - [ ] `obj/clone`
+  - [ ] `obj/lock`
+  - [ ] `obj/merge`
+  - [ ] `obj/ns`
+  - [ ] `opt`
+  - [ ] `objectid`
+  - [ ] `meta`
+  - [ ] `enum`
+  - [ ] `prop`
+  - [ ] `lazy`
+  - [ ] `observable`
+- Anything that has a TODO notice in the code.
+

package/index.js

@@ -0,0 +1,64 @@
+// 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/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@lumjs/core",
+  "version": "1.0.0-beta.1",
+  "main": "index.js",
+  "license": "MIT",
+  "repository":
+  {
+    "type": "git",
+    "url": "https://github.com/supernovus/lum.core.js.git"
+  },
+  "devDependencies":
+  {
+    "@lumjs/tests": "^1.0.0"
+  }
+}

package/src/context.js

@@ -0,0 +1,47 @@
+
+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;

package/src/descriptors.js

@@ -0,0 +1,243 @@
+
+const {InternalObjectId} = require('./objectid');
+const Enum = require('./enum');
+const {doesDescriptor,isObj,isComplex,def,B,F,N} = require('./types');
+
+  /**
+   * Get a property descriptor.
+   * 
+   * This is like `Object.getOwnPropertyDescriptor`, except that method
+   * fails if the property is inhereted. This method will travel through
+   * the entire prototype chain until it finds the descriptor.
+   * 
+   * @param {object|function} obj - Object to find a property in.
+   * @param {string} prop - Name of the property we want the descriptor of.
+   * @param {mixed} [defval] The fallback value if no descriptor is found.  
+   * 
+   * @returns {mixed} - The descriptor if found, `defval` if not.
+   */
+function getProperty(obj, prop, defval)
+{
+  if (!isComplex(obj)) throw new TypeError("Target must be an object or function");
+  // Yeah it looks like an infinite loop, but it's not.
+  while (true)
+  {
+    const desc = Object.getOwnPropertyDescriptor(obj, prop);
+    if (isObj(desc))
+    { // Found it.
+      return desc;
+    }
+
+    // Didn't find it, so let's try the next object in the prototype chain.
+    obj = Object.getPrototypeOf(obj);
+    if (!isComplex(obj))
+    { // We've gone as far up the prototype chain as we can, bye now!
+      return defval;
+    }
+  }
+}
+
+exports.getProperty = getProperty;
+
+const DESC_ID = new InternalObjectId({name: '$LumDescriptor'});
+const DESC_ADD = Enum(['ONE','SHORT', 'SET'], {flags: true});
+
+/**
+ * Create a magic Descriptor object.
+ * @param {object} desc - Descriptor template.
+ * @param {object} [opts] - Options (to be documented.)
+ * @returns {object} `desc`
+ */
+function descriptor(desc, opts={})
+{
+  if (!isObj(opts)) throw new TypeError("Options must be an object");
+
+  if (typeof desc === B)
+  { // This is a special case.
+    opts.accessorSafe = desc;
+    opts.add = DESC_ADD.ONE;
+    desc = {};
+  }
+
+  if (!isObj(desc)) 
+    throw new TypeError("First parameter (desc) must be a descriptor template object");
+
+  if (!Object.isExtensible(desc))
+    throw new RangeError("First parameter (desc) must not be locked, sealed, frozen, etc.");
+
+  const accessorSafe = (typeof opts.accessorSafe === B) 
+    ? opts.accessorSafe
+    : (desc.writable === undefined);
+  
+  DESC_ID.tag(desc);
+
+  // Add a function or other property.
+  const add = def(desc);
+
+  // Add a getter.
+  function accessor(name, getter, setter)
+  {
+    const adef = {configurable: true};
+    if (typeof getter === F) adef.get = getter;
+    if (typeof setter === F) adef.set = setter;
+    def(desc, name, adef);
+  }
+
+  add('accessorSafe', accessorSafe);
+
+  add('whenDone', function(func)
+  {
+    if (typeof func === F)
+    {
+      add('done', func);
+    }
+    return this;
+  });
+
+  if (typeof opts.done === F)
+  {
+    desc.whenDone(opts.done);
+  }
+
+  add('setValue', function (val, noClean)
+  {
+    if (this.get !== undefined || this.set !== undefined)
+    {
+      console.error("Accessor properties already defined", this);
+    }
+    else
+    {
+      this.value = val;
+    }
+    
+    return this;
+  });
+
+  if (accessorSafe)
+  {
+    function validate ()
+    {
+      if (this.value !== undefined)
+      { 
+        console.error("Data 'value' property defined", this);
+        return false;
+      }
+
+      for (const arg of arguments)
+      { // All accessor arguments must be functions.
+        if (typeof arg !== F) throw new TypeError("Parameter must be a function");
+      }
+
+      return true;
+    }
+
+    add('setGetter', function(func)
+    {
+      if (validate.call(this, func))
+        this.get = func;
+      return this;
+    });
+
+    add('setSetter', function(func)
+    {
+      if (validate.call(this, func))
+        this.set = func;
+      return this;    
+    });
+
+    add('setAccessor', function(getter, setter)
+    {
+      if (validate.call(this, getter, setter))
+      {
+        this.get = getter;
+        this.set = setter;
+      }
+      return this;
+    });
+
+  } // accessorSafe
+
+  if (opts.add)
+  {
+    const addTypes 
+      = (typeof opts.add === N) 
+      ? opts.add 
+      : DESC_ADD.SET;
+
+    function addBool(propname)
+    {
+      const setBool = function() 
+      { 
+        this[propname] = true; 
+        return this; 
+      }
+
+      if (addTypes & DESC_ADD.ONE)
+      {
+        const aname = propname[0];
+        accessor(aname, setBool);
+      }
+      if (addTypes & DESC_ADD.SHORT)
+      {
+        const aname = propname.substring(0,4);
+        accessor(aname, setBool);
+      }
+      if (addTypes & DESC_ADD.SET)
+      {
+        const aname = 'set'+ucfirst(propname);
+        accessor(aname, setBool);
+      }
+    }
+
+    addBool('configurable');
+    addBool('enumerable');
+    addBool('writable');
+
+  } // addBools
+
+  // Is the descriptor ready to be used?
+  accessor('isReady', function()
+  {
+    return doesDescriptor(this);
+  });
+
+  return desc;
+} // descriptor()
+
+exports.descriptor = descriptor;
+
+/**
+ * Get a Descriptor object.
+ * @param {object} desc - Either a Descriptor, or a descriptor template. 
+ * @returns {object}
+ */
+function getDescriptor(desc)
+{
+  return DESC_ID.is(desc) ? desc : descriptor(desc);
+}
+
+exports.getDescriptor = getDescriptor;
+
+/**
+ * A factory for building magic Descriptor objects.
+ */
+const DESC =
+{
+  get RO()    { return descriptor(true)  },
+  get CONF()  { return descriptor(true).c  },
+  get ENUM()  { return descriptor(true).e  },
+  get WRITE() { return descriptor(false).w },
+  get RW()    { return descriptor(false).c.w },
+  get DEF()   { return descriptor(true).c.e  },
+  get OPEN()  { return descriptor(false).c.e.w },
+}
+
+def(DESC)
+  ('make', descriptor)
+  ('is',   DESC_ID.isFunction())
+  ('get',  getDescriptor)
+  ('does', doesDescriptor)
+  ('ADD',  DESC_ADD);
+
+exports.DESC = DESC;
+

package/src/enum.js

@@ -0,0 +1,123 @@
+
+const {S,def,notNil,isObj} = require('./types')
+const {InternalObjectId} = require('./objectid');
+
+const ENUM_ID = new InternalObjectId({name: '$Enum'});
+
+/**
+ * A function to build magic Enum objects.
+ * 
+ * Like the built-in `Symbol`, this is called as a function, not a constructor.
+ * 
+ * @param {*} spec - TBD
+ * @param {*} [opts] - TBD
+ * @returns {object} A magic Enum object.
+ */
+function Enum (spec, opts={})
+{
+  if (!isObj(spec))
+  {
+    throw new TypeError("Enum spec must be an object");
+  }
+  if (!isObj(opts))
+  {
+    throw new TypeError("Enum options must be an object")
+  }
+
+  const anEnum = ENUM_ID.tag({});
+
+  function getVal (name, def)
+  {
+    if (opts.symbols)
+    { // We want to use symbols.
+      if (opts.globals)
+      {
+        return Symbol.for(name);
+      }
+      else
+      {
+        return Symbol(name);
+      }
+    }
+    else
+    { // Use the default.
+      return def;
+    }
+  }
+
+  function addVal(pName, sName, inVal)
+  {
+    const desc = {configurable: true, enumerable: true};
+    desc.value = getVal(sName, inVal);
+    def(anEnum, pName, desc);
+  }
+
+  if (Array.isArray(spec))
+  { // An array of strings is expected.
+    let counter = opts.counter ?? 1;
+
+    for (let i = 0; i < spec.length; i++)
+    {
+      const name = spec[i];
+      if (typeof name !== S)
+      {
+        throw new TypeError("Non-string passed in Lum.Enum object");
+      }
+
+      const val 
+        = opts.strings 
+        ? name 
+        : (opts.flags ? counter : i);
+
+      addVal(name, name, val);
+
+      if (opts.flags)
+      { // Increment the binary flag counter.
+        counter *= 2;
+      }
+    }
+  }
+  else
+  { // An object mapping of property name to value.
+    for (const pName in spec)
+    {
+      const val = spec[pName];
+      const sName = (typeof val === S) ? val : pName;
+      addVal(pName, sName, val);
+    }
+  }
+
+  if (notNil(opts.lock))
+  { // Use lock.
+    let lockOpts;
+    if (Array.isArray(opts.lock))
+    {
+      lockOpts = opts.lock;
+    }
+    else if (isObj(opts.lock))
+    {
+      lockOpts = [true, opts.lock, false];
+    }
+    else if (typeof opts.lock === B)
+    {
+      lockOpts = [opts.lock, null, false];
+    }
+    else 
+    {
+      lockOpts = [true, null, false];
+    }
+    return lock(anEnum);
+  }
+  else if (!opts.open) 
+  { // Use Object.freeze()
+    return Object.freeze(anEnum);
+  }
+
+  return anEnum;
+
+} // Enum
+
+// Add an 'is' method.
+def(Enum, 'is', ENUM_ID.isFunction());
+
+module.exports = Enum;

package/src/flags.js

@@ -0,0 +1,45 @@
+
+const {N} = require('./types');
+
+/**
+ * Add or remove a binary flag from a set of flags.
+ * @param {number} flags - An integer representing a set of flags.
+ * @param {number} flag - An integer representing the flag to add or remove.
+ * @param {boolean} [value=true] `true` means add, `false` means remove. 
+ * @returns {number} The `flags` with the `flag` added or removed accordingly.
+ */
+function setFlag(flags, flag, value=true)
+{
+  if (typeof flags !== N) throw new TypeError("Flags must be number");
+  if (typeof flag !== N) throw new TypeError("Flag must be number");
+
+  if (value)
+    flags = flags | flag;
+  else
+   flags = flags - (flags & flag);
+
+  return flags;
+}
+
+exports.setFlag = setFlag;
+
+/**
+ * Combine an entire set of flags into a single set.
+ * @param {...number} flag - Any number of flags you want to add.
+ * @returns {number} All the passed flags combined into one set.
+ */
+function allFlags()
+{
+  const flags = 0;
+  for (const arg of arguments)
+  {
+    if (typeof arg !== N)
+    {
+      throw new TypeError("Arguments must be numbers");
+    }
+    flags = flags | arg;
+  }
+  return flags;
+}
+
+exports.allFlags = allFlags

package/src/lazy.js

@@ -0,0 +1,102 @@
+
+const {S,F,isComplex} = require('./types');
+const prop = require('./prop');
+const {DESC} = require('./descriptors');
+
+/**
+ * Build a lazy initializer property.
+ *
+ * Basically the first time the property is accessed it's built.
+ * Subsequent accesses will use the already built property.
+ * This is an extension of the {@link prop} method, and indeed an
+ * alias called `prop.lazy()` is also available.
+ *
+ * @param {object} obj - The object to add the property to.
+ * @param {string} name - The name of the property to add.
+ * @param {function} initfunc - The function to initialize the property.
+ * 
+ *   This function will have `this` set to the `obj` parameter.
+ *   It will also be passed `name` as the sole parameter.
+ * 
+ * @param {mixed} [onset] How to handle assignment.
+ * 
+ *   If this is `true` then the new value will be assigned directly,
+ *   skipping the initialization process entirely.
+ * 
+ *   If this is `false` then any attempt at assignment will throw
+ *   a `ReferenceError` with a message indicating the property is read-only.
+ * 
+ *   If this is a `function` it will take two arguments, the
+ *   first being the value that is trying to be assigned, and
+ *   the second being the currently assigned value.
+ *   As with any getter or setter, `this` will be the `obj` itself.
+ *   The function must return the value to be assigned.
+ *   If it returns `undefined`, then the value was not valid,
+ *   and will not be assigned.
+ * 
+ *   If this is anything else, assignment will do nothing at all.
+ * 
+ * @param {object} [desc=DESC.CONF] The Descriptor for the property.
+ *
+ * @return {object} The object we defined the property on.
+ */
+function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
+{
+  if (!isComplex(obj))
+  {
+    throw new TypeError("obj parameter was not an object");
+  }
+  if (typeof name !== S)
+  {
+    throw new TypeError("name parameter was not a string");
+  }
+  if (typeof initfunc !== F)
+  {
+    throw new TypeError("initfunc parameter was not a function");
+  }
+
+  let value;
+  let setter = null;
+
+  function getter()
+  {
+    if (value === undefined)
+    {
+      value = initfunc.call(this, name);
+    }
+    return value;
+  }
+
+  if (onset === true)
+  { // Allow direct assignment.
+    setter = function(newval)
+    {
+      value = newval;
+    }
+  }
+  else if (onset === false)
+  { // Throw an error on assignment.
+    setter = function()
+    {
+      throw new ReferenceError("The "+name+" property is read-only");
+    }
+  }
+  else if (typeof onset === F)
+  { // A proxy method for assignment.
+    setter = function(newval)
+    {
+      const setval = onset.call(this, newval);
+      if (setval !== undefined)
+      {
+        value = setval;
+      }
+    }
+  }
+
+  prop(obj, name, getter, setter, desc);
+}
+
+// Gotta be one of the greatest lines...
+prop(prop, 'lazy', lazy);
+
+module.exports = lazy;