@lumjs/compat 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# 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] - 2022-07-29
+### Added
+- Initial release.
+
+[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/supernovus/lum.compat.js/releases/tag/v1.0.0
+

package/README.md

@@ -0,0 +1,56 @@
+# lum.compat.js
+
+As the libraries grow over time, features can change a lot, and backwards
+compatibility is not always easy to maintain.
+
+This library serves two purposes. The first is to be like the corresponding
+[lum/lum-compat](https://github.com/supernovus/lum.compat.php) PHP library, 
+offering some generic compatibility functions.
+
+The second is to be a repository for some older, deprecated functionality from
+the [@lumjs/core](https://github.com/supernovus/lum.core.js) library.
+
+By keeping some of the old sub-modules here as optional plugins, I can keep
+legacy code up and running until I can rewrite it to no longer use those
+features.
+
+## Entry Points
+
+To keep features simple and separated, there's a few different entry points
+exported from this library.
+
+### `@lumjs/compat` 
+
+The main entrypoint is reserved for generic compatibility functions.
+
+### `@lumjs/compat/v4-meta`
+
+This entry-point adds several overly convoluted meta-programming features that
+had been in the original `core` library in the legacy `v4` but during the 
+early stages of the rewrite I decided were just bloat that could be done better.
+
+| Core Property   | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `descriptors`   | A sub-module for creating magic Descriptor objects.       |
+| `DESC`          | The primary API for the `descriptors` sub-module.         |
+| `prop()`        | An `Object.defineProperty` wrapper using `descriptors`.   |
+
+These were all features I overthought and overdesigned, and added layers of
+complexity that were not required. The `prop()` function has been replaced by 
+`core.def()` which has a cleaner and simpler API and doesn't require the evil
+dark magic that was the `descriptors` module.
+
+## Official URLs
+
+This library can be found in two places:
+
+ * [Github](https://github.com/supernovus/lum.compat.js)
+ * [NPM](https://www.npmjs.com/package/@lumjs/compat)
+
+## Author
+
+Timothy Totten <2010@totten.ca>
+
+## License
+
+[MIT](https://spdx.org/licenses/MIT.html)

package/jsdoc.json

@@ -0,0 +1,33 @@
+{
+  "tags": 
+  {
+    "allowUnknownTags": true
+  },
+  "source":
+  {
+    "include": ["./lib"]
+  },
+  "opts": 
+  {
+    "destination": "./docs/api",
+    "recurse": true
+  },
+  "plugins": 
+  [
+    "plugins/markdown"
+  ],
+  "templates": 
+  {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": 
+    {
+      "outputSourceFiles": true
+    },
+    "path": "ink-docstrap",
+    "theme": "cerulean",
+    "navType": "vertical",
+    "linenums": true,
+    "dateFormat": "YYYY-MM-DD, hh:mm:ss"
+  }
+}

package/lib/descriptors.js

@@ -0,0 +1,210 @@
+const core = require('@lumjs/core');
+const {InternalObjectId,Enum,types} = core;
+const {doesDescriptor,isObj,isComplex,def,B,F,N} = types;
+
+// We moved getProperty() to the `@lumjs/core/obj` module.
+const getProperty = core.obj.getProperty;
+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/lib/index.js

@@ -0,0 +1,27 @@
+// Compatibility jank.
+
+const semver = require('semver');
+const PKGJSON = 'package.json';
+
+// A super simplistic package info wrapper.
+class Package
+{
+  constructor(pkg)
+  { 
+    this.file = pkg+'/'+PKGJSON;
+    this.info = require(this.conf);
+    this.version = semver.parse(this.info.version);
+  }
+
+  satisfies(range, options)
+  {
+    return semver.satisfies(this.version, range, options);
+  }
+
+  static new(pkg)
+  {
+    return new Package(pkg);
+  }
+}
+
+exports.Package = Package;

package/lib/prop.js

@@ -0,0 +1,164 @@
+const core = require('@lumjs/core');
+const {isObj,isNil,notNil,isProperty,unbound,F} = core.types;
+const {cloneIfLocked} = core.obj;
+
+const {DESC,getDescriptor} = require('./descriptors');
+
+/**
+ * A magic wrapper for Object.defineProperty()
+ *
+ * Rather than documenting the arguments in the usual manner, I'm
+ * going to simply show all of the ways this method can be called.
+ * 
+ * Anywhere the `target` parameter is shown, this parameter can be an `object` or `function`.
+ * It's the target to which we're adding new properties.
+ * 
+ * Anywhere the `property` parameter is shown, this parameter can be specified in two different
+ * forms. The first and simplest is as a `string` in which case it's simply the name of the property we're adding.
+ * The second more advanced form is as an `object`. If it is specified as an object, then it is a set of special options.
+ * In this case, a property of that `property` object called `name` will be used as the name of the property.
+ * If the `name` property is absent or `undefined`, it's the same as not passing the `property` parameter at all, 
+ * and a *bound* function will be returned, using the custom options as its bound defaults.
+ * 
+ * See below the usage 
+ *
+ * `Lum.prop(object)`
+ *
+ *   Return a function that is a bound copy of this function with
+ *   the object as it's first parameter.
+ *
+ * `Lum.prop(object, property)`
+ *
+ *   Add a property to the object which is mapped to a bound copy of
+ *   this function with the object as it's first parameter.
+ *
+ * `Lum.prop(object, property, function, function)`
+ *
+ *   Add a getter and setter property with the default descriptor.
+ *
+ * `Lum.prop(object, property, function, function, object)`
+ *
+ *   Add a getter and setter property with specified Descriptor options.
+ *   Do not use `get`, `set`, or `value` in the descriptor options.
+ *
+ * `Lum.prop(object, property, function, null, object)`
+ *
+ *   Add a getter only with specified descriptor options.
+ *   Same restrictions to the descriptor options as above.
+ *   You can specify `{}` as the descriptor options to use the defaults.
+ *
+ * `Lum.prop(object, property, null, function, object)`
+ *
+ *   Add a setter only with specified descriptor options.
+ *   Same restrictions as above, and again you can use `{}` for defaults.
+ *
+ * `Lum.prop(object, property, !null)`
+ *
+ *   Add a property with the specified non-null value.
+ *   This uses the default descriptor.
+ *
+ * `Lum.prop(object, property, !null, object)`
+ *
+ *   Add a property value with the specified descriptor options.
+ *   Has the same restrictions to the descriptor options as above.
+ *
+ * `Lum.prop(object, property, null, object)`
+ *
+ *   Add a property using the descriptor object alone.
+ *   Use the newer and shorter `def()` function instead.
+ * 
+ * `Lum.prop(object, property, Descriptor)`
+ * 
+ *   If you use `DESC.make()` or `descriptor()` to build a magic
+ *   descriptor object, you can pass it and it'll be used with
+ *   a few bonus features I need to document that aren't supported by
+ *   the otherwise equivalent `def(object,property,descriptor)` call.
+ *
+ * @alias module:@lumjs/compat/v4-meta.prop
+ * @deprecated Replaced by `@lumjs/core.def` method. 
+ */
+function prop(obj, name, arg1, arg2, arg3)
+{
+  let opts;
+
+  const isUnbound = unbound(this, true, true);
+
+  if (isObj(name))
+  { // A way to set some special options.
+    opts = name;
+    name = opts.name;
+  }
+  else if (isUnbound)
+  { // Use the default options.
+    opts = isObj(prop.options) ? prop.options : {};
+  }
+  else if (isObj(this))
+  { // This is already a bound copy, so `this` is the options.
+    opts = this;
+  }
+  else 
+  { // Something weird is going on here...
+    throw new Error("Invalid `this` in a prop() function call");
+  }
+
+  if (isNil(name))
+  { // A special case, returns a copy of this function bound to the object.
+    return prop.bind(opts, obj);
+  }
+  else if (!isProperty(name))
+  { // The property must in every other case be a string.
+    throw new Error("property name must be a string or Symbol");
+  }
+
+  let desc;
+
+  if (arg1 === undefined && arg2 === undefined)
+  { // Another special case, the property is a bound version of this.
+    return prop(obj, name, prop.bind(opts, obj));
+  }
+  else if (DESC.is(arg1) && arg2 === undefined)
+  { // Yet another special case.
+    if (arg1.isReady)
+    { // Already has a value or get/set properties assigned.
+      desc = arg1;
+    }
+    else 
+    { // We'll need to call setValue(), setGetter(), etc, then done().
+      return arg1.whenDone(function()
+      {
+        return prop(obj, name, this);
+      });
+    }
+  }
+  else if (typeof arg1 === F && typeof arg2 === F)
+  { // A getter and setter were specified.
+    desc = getDescriptor(isObj(arg3) ? cloneIfLocked(arg3) : DESC.CONF);
+    desc.setAccessor(arg1, arg2);
+  }
+  else if (isObj(arg3))
+  { // A custom descriptor for an accessor, find the accessor.
+    desc = getDescriptor(cloneIfLocked(arg3));
+    if (typeof arg1 === F)
+    { // A getter-only accessor.
+      desc.setGetter(arg1);
+    }
+    else if (typeof arg2 === F)
+    { // A setter-only accessor.
+      desc.setSetter(arg2);
+    }
+  }
+  else
+  { // Not a getter/setter, likely a standard value.
+    desc = getDescriptor(isObj(arg2) ? cloneIfLocked(arg2) : DESC.CONF);
+    
+    if (notNil(arg1))
+    { // If you really want a null 'value', use a custom descriptor.
+      desc.setValue(arg1);
+    }
+  }
+
+  // If we reached here, we should have a valid descriptor now.
+  return Object.defineProperty(obj, name, desc);
+}
+
+module.exports = prop;

package/lib/v4-meta.js

@@ -0,0 +1,14 @@
+/**
+ * Lum.js v4 Meta-Programming helpers.
+ * @module @lumjs/compat/v4-meta
+ */
+
+/**
+ * Descriptors magic objects module.
+ */
+exports.descriptors = require('./descriptors');
+
+/**
+ * The `prop()` function.
+ */
+exports.prop = require('./prop');

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lumjs/compat",
+  "version": "1.0.0",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./v4-meta": "./lib/v4-meta.js",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supernovus/lum.compat.js.git"
+  },
+  "dependencies": {
+    "@lumjs/core": "^1.1.0",
+    "semver": "^7.3.7"
+  },
+  "scripts":
+  {
+    "build-docs": "jsdoc -c ./jsdoc.json"
+  }
+}