@lumjs/compat 1.3.1 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0]
+### Removed
+- Literally everything from the 1.x package. It's left in the `v1` branch.
+### Added
+- `exportModule()` function meant as a compatibility bridge between ES Modules
+  and CommonJS. It's simplistic and is only meant as a temporary measure to
+  add some layer of backwards-compatibility when migrating from CJS to ESM.
+### Changed
+- Cleaned up README to trim anything to do with the removed sub-modules.
+### Fixed
+- Added missing link references to this CHANGELOG.
+
+## [1.4.0] - 2023-01-06
+### Changed
+- Made the `v4` set not use any `ModuleBuilder` features anymore.
+- Moved `ModuleBuilder` from core into the `modulebuilder` namespace.
+
 ## [1.3.1] - 2022-10-18
 ### Fixed
 - The `v4/loadtracker` was trying to call a function from the old `Lum` global.
@@ -43,7 +60,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
-[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/supernovus/lum.compat.js/compare/v1.4.0...v2.0.0
+[1.4.0]: https://github.com/supernovus/lum.compat.js/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/supernovus/lum.compat.js/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/supernovus/lum.compat.js/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/supernovus/lum.compat.js/compare/v1.1.0...v1.2.0

package/README.md

@@ -1,41 +1,20 @@
 # lum.compat.js
 
-As the libraries grow over time, features can change a lot, and backwards
-compatibility is not always easy to maintain.
+Compatibility helpers.
 
-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.
+As of version 2.0, this is a nano-package with zero dependencies that
+currently provides a simple bridge between CommonJS and ES Modules.
 
-The second is to be a repository for some older, deprecated functionality from
-the [@lumjs/core](https://github.com/supernovus/lum.core.js) library.
+## Branches
 
-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.
+### `main`
 
-## Entry Points
+The `2.x` releases are from this branch.
 
-To keep features simple and separated, there's a few different entry points
-exported from this library.
+### `v1.x`
 
-### `@lumjs/compat` 
-
-The main entrypoint is reserved for generic compatibility functions.
-
-### `@lumjs/compat/v4`
-
-The `v4` compatibility namespace. Includes all `v4` modules in one simple object.
-
-| Property        | Description                                               |
-| --------------- | --------------------------------------------------------- |
-| `descriptors`   | The `v4/descriptors` module.                              |
-| `DESC`          | The `v4/descriptors.DESC` factory object.                 |
-| `prop()`        | The `v4/prop` module.                                     |
-| `deprecated()`  | The `v4/deprecated` module.                               |
-| `LoadTracker`   | The `v4/loadtracker` module.                              |
-| `Promise`       | The `v4/promise` module.                                  |
-| `obj`           | The `v4/object-helpers` module.                           |
+The original package was a bunch of compatibility wrappers for [@lumjs/core],
+and covered versions `1.0.0` through `1.4.0`.
 
 ## Official URLs
 
@@ -51,3 +30,5 @@ Timothy Totten <2010@totten.ca>
 ## License
 
 [MIT](https://spdx.org/licenses/MIT.html)
+
+[@lumjs/core]: https://github.com/supernovus/lum.core.js

package/lib/index.js

@@ -1,27 +1,138 @@
-// 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.file);
-    this.version = semver.parse(this.info.version);
-  }
+/**
+ * Compatibility jank.
+ * @module @lumjs/compat
+ */
 
-  satisfies(range, options)
-  {
-    return semver.satisfies(this.version, range, options);
-  }
+const ESM = '__esModule';
+const DEF = 'default';
+
+/**
+ * Make an exporter closure: `(key,value) => ...`;
+ * 
+ * Properties added with the closure are configurable and enumerable,
+ * but not writable. It does NOT support accessors (getter/setter).
+ * 
+ * This is mostly just designed for use in the exportModule() function.
+ * @param {(object|function)} obj - Target to export properties to.
+ * @returns {function}
+ */
+function exporter(obj) {
+  return (key, value) => Object.defineProperty(obj, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+  });
+}
+
+/**
+ * Property name filtering or renaming function.
+ * @callback module:@lumjs/compat~ExportUse
+ * @param {string} prop - Property name in ES Module.
+ * @returns {(string|false|undefined|null)} Property name for default export.
+ */
+
+/**
+ * Export an ES Module type definition with some CommonJS compatibility.
+ * 
+ * This takes an ES Module that was loaded using `require()`, and will 
+ * attempt to create a CommonJS export that adds (most) named exports 
+ * as properties of the default export.
+ * 
+ * Example usage:
+ * 
+ * ```js
+ * const { exportModule } = require('@lumjs/compat');
+ * module.exports = exportModule(require('./index.mjs'));
+ * ```
+ * 
+ * @param {object} mod - The ES Module object.
+ * 
+ * If this has a property named `default` that is either an `object`
+ * or a `function` then it will have properties added to it for each
+ * of the named exports (with a few exceptions configurable with options),
+ * and then the default export will be returned.
+ * 
+ * NOTE: if the default export already has a property with an exported name,
+ * that export will be skipped rather than overwriting the existing value.
+ * 
+ * If `mod.default` is NOT an object or function then the `mod` itself with
+ * no modifications will be the return value from this function.
+ * 
+ * @param {object} [opts] Advanced options.
+ * 
+ * @param {(string|symbol|false)} [opts.esmName="__esModule"] ESM Object key.
+ * 
+ * If this is a string or symbol, it will be used as the name of a property
+ * to add to the default export that will contain the full `mod` object.
+ * 
+ * Set this to `false` to disable this feature entirely.
+ *
+ * NOTE: unlike the named exports, this special property WILL overwrite an
+ * existing property with the same name, so be sure it's something that won't
+ * conflict. The default `__esModule` is meant to mask the boolean property
+ * of the same name that Node adds to ES Modules loaded via require().
+ * 
+ * @param {boolean} [opts.skipDefault=true] Skip the `default` property?
+ * 
+ * If true (default) it skips adding the `default` property, which would
+ * literally just be a link to itself and thus rather useless IMHO.
+ * 
+ * You can set this to false if you really want the self-reference,
+ * or you could use `opts.map` to rename it to something else.
+ * 
+ * @param {module:@lumjs/compat~ExportUse} [opts.use] Advanced use only!
+ * 
+ * This will be called for every enumerable string-keyed property in `mod`.
+ * The context (`this`) in non-closures will be the `opts` object.
+ * 
+ * It's return value will be used to determine the property name that
+ * will be used on the default export for the associated named export.
+ * 
+ * - A `string` will be used as the property name on the default export.
+ * - `undefined` or `null` is the same as returning the name unchanged.
+ * - `false` may be used to skip adding that property entirely.
+ * 
+ * For the majority of packages this feature is likely unnecessary,
+ * only use it if you have a really good reason to customize the exports!
+ * 
+ * @returns {(object|function)} Either `mod.default` or `mod` itself.
+ * See above for details on how the return value is determined.
+ */
+function exportModule(mod, opts={}) {
+  if (mod && typeof mod === 'object' && mod.default
+    && (typeof mod.default === 'object' 
+    ||  typeof mod.default === 'function')
+  ) { // Has an object/function default export.
+    let modef = mod.default;
+    let esKey = opts.esmName ?? ESM;
+    let noDef = opts.skipDefault ?? true;
+    let use  = (typeof opts.use === 'function') ? opts.use : null;
+    let addExport = exporter(modef);
+    let props = Object.keys(mod);
+
+    if (typeof esKey === 'string' || typeof esKey === 'symbol')
+    { // Add a reference to the full module.
+      addExport(esKey, mod);
+    }
+
+    for (let ep of props)
+    {
+      if (noDef && ep === DEF) continue;
+
+      let dp = use ? (use.call(opts, ep) ?? ep) : ep;
+      if (dp === false) continue;
+      if (Object.hasOwn(modef, dp)) continue;
+
+      let value = mod[ep];
+      if (value === undefined) continue;
+
+      addExport(dp, value);
+    }
 
-  static new(pkg)
-  {
-    return new Package(pkg);
+    return modef;
   }
+  
+  return mod;
 }
 
-exports.Package = Package;
+module.exports = {exporter, exportModule}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lumjs/compat",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "main": "lib/index.js",
+  "engine":
+  {
+    "node": ">=22.0.0"
+  },
   "exports": {
     ".": "./lib/index.js",
-    "./v4-meta": "./lib/v4/index.js",
-    "./v4": "./lib/v4/index.js",
-    "./v4/meta": "./lib/v4/index.js",
-    "./v4/*": "./lib/v4/*.js",
     "./package.json": "./package.json"
   },
   "license": "MIT",
@@ -15,12 +15,7 @@
     "type": "git",
     "url": "https://github.com/supernovus/lum.compat.js.git"
   },
-  "dependencies": {
-    "@lumjs/core": "^1.7.1",
-    "semver": "^7.3.7"
-  },
-  "scripts":
-  {
+  "scripts": {
     "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/lib/v4/deprecated.js

@@ -1,122 +0,0 @@
-/**
- * Mark a function/method/property as deprecated.
- *
- * Adds a warning to the Console that the method is deprecated.
- *
- * It can also optionally give example replacement code, and run a function 
- * that will call the replacement code automatically.
- *
- * @param {string} name  The name of the deprecated method/property/etc.
- *
- *   This should actually be the full method signature, or at least the
- *   signature matching what a call to the deprecated method made.
- *
- *   So rather than 'someOldMethod', use 'MyClass.someOldMethod(foo, bar)'
- *   as a more detailed name. This is only used in the Console warning.
- *
- *   This is the only mandatory parameter.
- *
- * @param {mixed} [replace={}]  Replacement options.
- * 
- *   If this is a {string}, it is the same as passing an {object} with
- *   the following options specified:
- *
- *     ```{msg: replace}```
- *
- *   If it is a {function}, it is the same as passing an {object} with
- *   the following options specified:
- *
- *     ```{exec: replace, msg: true, strip: true}```
- *
- *   If it is an {object}, then it will be a set of options:
- *
- *     "exec" {function}
- *
- *       If specified, this function will be called and the value returned.
- *       No paramters are passed to the function, so it should be a simple 
- *       anonymous closure which simply calls the actual replacement code.
- *
- *     "msg" {string|boolean}
- *
- *       If this is a {string} it will be added to the warning output.
- *
- *       If this is `true` and `exec` is set, we will extract the function
- *       text using `exec.toString()` and add it to the warning output.
- *
- *       In any other cases, no replacement message will be appended.
- *
- *     "strip" {boolean}
- *
- *       If this is `true`, then we will strip `'function() { return '`
- *       from the start of the function text (whitespace ignored), as well
- *       as stripping '}' from the very end of the function text.
- *
- *       This is only applicable if `exec` is set, and `msg` is `true`.
- *
- *   If the `replace` value is none of the above, it will be ignored.
- *
- * @return {mixed}  The output is dependent on the parameters passed.
- *
- * If `replace` is a function or an object with 
- *
- * In any other case the return value will be undefined.
- *
- * @alias module:@lumjs/compat/v4/deprecated
- */
-module.exports = function (name, replace={})
-{
-  const DEP_MSG = ':Deprecated =>';
-  const REP_MSG = ':replaceWith =>';
-
-  if (typeof replace === S)
-  { // A string replacement example only.
-    replace = {msg: replace};
-  }
-  else if (typeof replace === F)
-  { // A function replacement.
-    replace = {exec: replace, msg: true, strip: true};
-  }
-  else if (!is_obj(replace))
-  { // Not an object, that's not valid.
-    replace = {};
-  }
-
-  const msgs = [DEP_MSG, name];
-  const exec = (typeof replace.exec === F) 
-    ? replace.exec
-    : null;
-
-  if (exec && replace.msg === true)
-  { // Extract the function text.
-    const strip = (typeof replace.strip === B)
-      ? replace.strip
-      : false;
-
-    let methtext = replace.exec.toString();
-
-    if (strip)
-    { // Remove wrapping anonymous closure function.
-      methtext = methtext.replace(/^function\(\)\s*\{\s*(return\s*)?/, '');
-      methtext = methtext.replace(/\s*\}$/, '');
-      // Also support arrow function version.
-      methtext = methtext.replace(/^\(\)\s*\=\>\s*/, '');
-    }
-
-    // Set the replacement msg to the method text.
-    replace.msg = methtext;
-  }
-
-  if (typeof replace.msg === 'string')
-  { // A replacement message.
-    msgs.push(REP_MSG, replace.msg);
-  }
-
-  // Show the messages.
-  console.warn(...msgs);
-
-  // Finally, call the replacement function if it was defined.
-  if (exec)
-  {
-    return exec();
-  }
-}

package/lib/v4/descriptors.js

@@ -1,217 +0,0 @@
-/**
- * Descriptors magic objects library.
- * @module @lumjs/compat/v4/descriptors
- */
-
-const core = require('@lumjs/core');
-const {InternalObjectId,Enum,types} = core;
-const {doesDescriptor,isObj,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`
- * @alias module:@lumjs/compat/v4/descriptors.descriptor
- */
-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}
- * @alias module:@lumjs/compat/v4/descriptors.getDescriptor
- */
-function getDescriptor(desc)
-{
-  return DESC_ID.is(desc) ? desc : descriptor(desc);
-}
-
-exports.getDescriptor = getDescriptor;
-
-/**
- * A factory for building magic Descriptor objects.
- * @alias module:@lumjs/compat/v4/descriptors.DESC
- */
-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/v4/index.js

@@ -1,51 +0,0 @@
-/**
- * Lum.js v4 compatibility set.
- * 
- * Now uses lazy-loading for all properties.
- * 
- * @module @lumjs/compat/v4
- */
-
-const {can,from} = require('@lumjs/core').buildModule(module);
-
-/**
- * @name module:@lumjs/compat/v4.descriptors
- * @see module:@lumjs/compat/v4/descriptors
- */
-can('descriptors');
-
-/**
- * @name module:@lumjs/compat/v4.DESC
- * @see module:@lumjs/compat/v4/descriptors.DESC
- */
-from('descriptors', true, 'DESC');
-
-/**
- * @name module:@lumjs/compat/v4.prop
- * @see module:@lumjs/compat/v4/prop
- */
-can('prop');
-
-/**
- * @name module:@lumjs/compat/v4.deprecated
- * @see module:@lumjs/compat/v4/deprecated
- */
-can('deprecated');
-
-/**
- * @name module:@lumjs/compat/v4.LoadTracker
- * @see module:@lumjs/compat/v4/loadtracker
- */
-can('LoadTracker', true);
-
-/**
- * @name module:@lumjs/compat/v4.Promise
- * @see module:@lumjs/compat/v4/promise
- */
-can('Promise', true);
-
-/**
- * @name module:@lumjs/compat/v4.obj
- * @see module:@lumjs/compat/v4/object-helpers
- */
-can('obj', './object-helpers');