@lumjs/compat 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.
@@ -48,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,15 +1,13 @@
 {
   "name": "@lumjs/compat",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "main": "lib/index.js",
+  "engine":
+  {
+    "node": ">=22.0.0"
+  },
   "exports": {
     ".": "./lib/index.js",
-    "./modulebuilder": "./lib/modulebuilder/index.js",
-    "./modulebuilder/into-core": "./lib/modulebuilder/into-core.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",
@@ -17,12 +15,7 @@
     "type": "git",
     "url": "https://github.com/supernovus/lum.compat.js.git"
   },
-  "dependencies": {
-    "@lumjs/core": "^1.8.0",
-    "semver": "^7.3.7"
-  },
-  "scripts":
-  {
+  "scripts": {
     "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/lib/modulebuilder/index.js

@@ -1,414 +0,0 @@
-
-const 
-{
-  S,F,B,
-  isObj,needObj,needType,
-  def,lazy
-} = require('@lumjs/core/types');
-
-const clone = require('@lumjs/core/obj').duplicateOne;
-
-// Methods we want to export in the functional API.
-const BUILD_METHODS = ['has', 'can', 'from', 'set'];
-
-// Fallback locale
-const DLOC = 'en-US';
-
-/**
- * A class to make building modules easier.
- * 
- * Basically wraps calls to `require()`, `def()`, `lazy()`,
- * and assignments to `module.exports` into a simple set of methods.
- * 
- * @exports module:@lumjs/compat/modulebuilder
- */
-class ModuleBuilder
-{
-  /**
-   * Build a new ModuleBuilder instance.
-   * 
-   * @param {object} targetModule - The `module` context variable.
-   * @param {object} [opts] - Options to change some default settings.
-   * @param {boolean} [opts.configurable=false] Default `configurable` value.
-   * @param {boolean} [opts.enumerable=true] Default `enumerable` value.
-   * @param {boolean} [opts.writable=false] Default `writable` value.
-   * 
-   * @param {number} [opts.nested=NESTED_ERROR] How to handle nested names.
-   * 
-   * If the `name` parameter in either the `has()` or `can()` method is passed 
-   * as the path to a nested module with one or more `/` characters, 
-   * this mode will determine how we derive the property name. 
-   * 
-   * For each mode, we'll use an example `name` of `./some/nested/path`.
-   * 
-   * - `ModuleBuilder.NESTED_ERROR` `[0]` (default mode)
-   *   Throw an `Error` saying paths are unhandled.
-   * - `ModuleBuilder.NESTED_FIRST` `[1]`
-   *   Use the first (non-dot) path element, e.g. `some`
-   * - `ModuleBuilder.NESTED_LAST` `[2]`
-   *   Use the last path element, e.g. `path`
-   * - `ModuleBuilder.NESTED_CAMEL` `[3]`
-   *   Convert the name to camelCase, e.g. `someNestedPath`
-   * 
-   * It's always possible to set the `conf.module` parameter manually as well,
-   * which avoids the need to generate a separate parameter name.
-   * 
-   * @param {(string|boolean)} [opts.withLocale=false] Use locales?
-   * 
-   * If this is a `string` it's the name of the locale (e.g. `en-US`).
-   * 
-   * If this is `true` we'll use the default locale as determined by
-   * [getLocale()]{@link module:@lumjs/core/strings.getLocale}.
-   * 
-   * If this is `false` we won't use locales (unless the `NESTED_CAMEL`
-   * mode is in use, in which case we'll use the default locale.)
-   * 
-   */
-  constructor(targetModule, opts={})
-  {
-    needObj(opts, 'opts was not an object');
-    needObj(targetModule, 'targetModule was not an object');
-    needObj(targetModule.exports, 'targetModule.exports was not an object');
-    needType(F, targetModule.require, 'targetModule.require was not a function');
-
-    this.module = targetModule;
-
-    this.configurable = opts.configurable ?? false;
-    this.enumerable   = opts.enumerable   ?? true;
-    this.writable     = opts.writable     ?? false;
-
-    this.nested = opts.nested ?? ModuleBuilder.NESTED_ERROR;
-
-    if (opts.withLocale)
-    { // Initialize the strings here.
-      this.withLocale(opts.locale);
-    }
-  }
-
-  // Get a descriptor for a module export.
-  requireDescriptor(name, conf={})
-  {
-    if (typeof conf === S)
-    { // A quick shortcut for setting module name.
-      conf = {module: conf};
-    }
-    else if (conf === true)
-    { // Use the lowercase name as the module.
-      conf = {module: this.$lc(name)};
-    }
-    else if (typeof conf.getter === F || typeof conf.setter === F)
-    { // It's an accessor-style descriptor already.
-      return conf;
-    }
-
-    let value = conf.value;
-    
-    if (value === undefined)
-    {
-      if (typeof conf.module === S)
-        name = conf.module; 
-      if (!name.startsWith('./'))
-        name = './'+name;
-
-      value = this.module.require(name);
-
-      if (value && conf.prop && value[conf.prop] !== undefined)
-      { 
-        value = value[conf.prop];
-      }
-    }
-
-    const configurable = conf.configurable ?? this.configurable;
-    const enumerable   = conf.enumerable   ?? this.enumerable;
-    const writable     = conf.writable     ?? this.writable;
-
-    return {configurable, enumerable, writable, value};
-  }
-
-  $lc(name)
-  {
-    return name.toLocaleLowerCase(this.locale ?? DLOC);
-  }
- 
-  // Normalize a property name.
-  $normalizeProperty(name)
-  {
-    if (name.startsWith('./'))
-    { // Get rid of the prefix.
-      name = name.substring(2);
-    }
-
-    if (name.includes('/'))
-    { // Multiple paths found.
-      const names = name.split('/');
-      if (this.nested === ModuleBuilder.NESTED_FIRST)
-      {
-        name = names[0];
-      }
-      else if (this.nested === ModuleBuilder.NESTED_LAST)
-      {
-        name = names[names.length-1];
-      }
-      else if (this.nested === ModuleBuilder.NESTED_CAMEL)
-      {
-        name = this.$normalizeWithCamelCase(names);
-      }
-      else 
-      {
-        throw new Error("No valid nested path handling method was set");
-      }
-    }
-
-    return name;
-  }
-
-  withLocale(loc)
-  {
-    if (this.strings === undefined)
-    { // Load the strings library.
-      this.strings = require('@lumjs/core/strings');
-    }
-
-    if (this.locale === undefined)
-    { // Set the locale.
-      if (typeof loc === S)
-      { // Use an explicitly passed value.
-        this.locale = loc;
-      }
-      else 
-      { // Use the default locale.
-        this.locale = this.strings.getLocale();
-      }
-    }
-  }
-
-  $normalizeWithCamelCase(names)
-  {
-    this.withLocale();
-    let name = names.shift().toLocaleLowerCase(this.locale);
-    for (const path in names)
-    {
-      name += this.strings.ucfirst(path, true, this.locale);
-    }
-    return name;
-  }
-  
-  /**
-   * Export a module directly.
-   * 
-   * @param {string} name - The property name to export.
-   *
-   * @param {(object|string|true)} [conf] Additional export configuration options.
-   * 
-   * If this is a `string` instead of an `object`, it's assumed to be the
-   * `conf.module` value.
-   * 
-   * If this is `true` then the `conf` will be set with `module` being the
-   * lowercase version of `name`.
-   * 
-   * @param {string} [conf.module=`./${name}`] The module to `require()`.
-   * @param {string} [conf.prop] If set, we want an exported property
-   * of this name from the loaded module.
-   * 
-   * If not set, the entire loaded module will be our exported value.
-   * 
-   * @param {boolean} [conf.configurable=this.configurable] 
-   * Descriptor `configurable` value.
-   * @param {boolean} [conf.enumerable=this.enumerable] 
-   * Descriptor `enumerable` value.
-   * @param {boolean} [conf.writable=this.writable] 
-   * Descriptor `writable` value.
-   * 
-   * @param {*} [conf.value] An explicit value to set.
-   * 
-   * This skips the `require()` call entirely.
-   * 
-   * @returns {object} `this`
-   */
-  has(name, conf={})
-  {
-    const pname = this.$normalizeProperty(name);
-    const desc = this.requireDescriptor(name, conf);
-    def(this.module.exports, pname, desc);
-    return this;
-  }
-
-  /**
-   * Export a lazy-loaded module.
-   * 
-   * @param {string} name - The property name to export.
-   * 
-   * @param {object} [conf] Additional export configuration options.
-   * 
-   * In addition to all the options supported by 
-   * [has()]{@link module:@lumjs/core/modules#has}
-   * this also supports one further option.
-   * 
-   * @param {object} [conf.lazy] Advanced options for the `lazy()` call.
-   * 
-   * If not specified, sane defaults will be used, that ensures the
-   * `enumerable` descriptor property for the lazy getter is set the
-   * same as the final descriptor property once its loaded.
-   * 
-   * @returns {object} `this`
-   */
-  can(name, conf={})
-  {
-    const pname = this.$normalizeProperty(name);
-    const enumerable = conf.enumerable ?? this.enumerable;
-    const lazyOpts = isObj(conf.lazy) ? conf.lazy : {enumerable};
-    const getter = () => this.requireDescriptor(name, conf);
-    lazy(this.module.exports, pname, getter, lazyOpts);
-    return this;
-  }
-
-  /**
-   * Re-export some exported properties from a module.
-   * 
-   * By default this uses `has()` to define the exports, but that
-   * can be changed using special parameter values.
-   * 
-   * @param {string} modname - The module to export the properties from.
-   * @param  {...any} libs - What we're exporting.
-   * 
-   * If this is a `string` it is the name of an exported property we want to
-   * re-export directly.
-   * 
-   * If this is `true`, all subsequent values will be exported using `can()`.
-   * 
-   * If this is `false`, all subsequent values will be exported using `has()`.
-   * 
-   * If this is an `object`, then it's considered the `conf` parameter for
-   * the `has()` or `can()` methods. If the `conf` does not have a `module`
-   * property, the `modname` will be assigned as the `module` property.
-   * You cannot set the `prop` property, as it's overwritten for every 
-   * exported property.
-   * 
-   * @returns {object} `this`
-   */
-  from(modname, ...libs)
-  {
-    let func = 'has';
-    let curConf = {module: modname};
-    for (const lib of libs)
-    {
-      if (isObj(lib))
-      { // Change the current config.
-        curConf = clone(lib);
-        if (curConf.module === undefined)
-        { // Make sure the module name is assigned.
-          curConf.module = modname;
-        }
-      }
-      else if (typeof lib === B)
-      { // Change the function we're calling.
-        func = lib ? 'can' : 'has';
-      }
-      else if (typeof lib === S)
-      {
-        const conf = clone(curConf);
-        conf.prop = lib;
-        this[func](lib, conf);
-      }
-      else 
-      {
-        throw new TypeError("libs must be strings, booleans, or objects");
-      }
-    }
-    return this;
-  }
-
-  /**
-   * Define an exported property in our module.
-   * 
-   * This is literally just a wrapper around the
-   * [def()]{@link module:@lumjs/core/types.def} method,
-   * that passes `this.module.exports` as the `obj` parameter.
-   * 
-   * @param {*} name - See `def()` for details.
-   * @param {*} value - See `def()` for details.
-   * @param {*} opts - See `def()` for details.
-   * @returns {(object|function)} What is returned may vary:
-   * 
-   * If the `def()` returns a *bound* copy of itself, we'll return that
-   * bound function directly.
-   * 
-   * In any other case, we return `this` ModuleBuilder instance.
-   */
-  set(name, value, opts)
-  {
-    const retval = def(this.module.exports, name, value, opts);
-    if (typeof retval === F && isObj(retval.$this) && retval.$this.bound === retval)
-    { // A bound copy was returned, we're going to return it directly.
-      return retval;
-    }
-    return this;
-  }
-
-  /**
-   * Create a functional API for the ModuleBuilder class.
-   * 
-   * Basically makes a new `ModuleBuilder` instance, then creates standalone 
-   * closure functions that wrap the main instance methods.
-   * 
-   * These functions can be imported into a namespace directly.
-   * They each have a special `builder` property which is a reference
-   * to the underlying `ModuleBuilder` instance.
-   * 
-   * There's also a `builder` property in the exported function list,
-   * as well as a copy of the `def()` method for quick exporting.
-   * 
-   * Example usage:
-   * 
-   * ```js
-   * const {has,can,from,set} 
-   *  = require('@lumjs/compat/modulebuilder').ModuleBuilder.build(module);
-   * 
-   * // exports.foo = require('./foo');
-   * has('foo'); 
-   * 
-   * // exports.someNestedPath = require('./some/nested/path');
-   * has('./some/nested/path'); 
-   * 
-   * ```
-   * 
-   * @param {object} targetModule - The `module` for the Builder instance.
-   * @param {object} [opts] - Any options for the Builder instance.
-   * @returns {object} An object containing the closure functions.
-   */
-  static build(targetModule, opts)
-  {
-    const builder = new this(targetModule, opts);
-    const funcs = {builder, def};
-    for (const name of BUILD_METHODS)
-    {
-      const func = function()
-      {
-        return builder[name](...arguments);
-      }
-      def(func, 'builder', builder);
-      funcs[name] = func;
-    }
-    return funcs;
-  }
-
-  /**
-   * A static alternative to `new ModuleBuilder()`;
-   * 
-   * @param {object} targetModule 
-   * @param {object} [opts] 
-   * @returns {object} The new `ModuleBuilder` instance.
-   */
-  static new(targetModule, opts)
-  {
-    return new this(targetModule, opts);
-  }
-
-}
-
-def(ModuleBuilder, 'NESTED_ERROR', 0)
-def(ModuleBuilder, 'NESTED_FIRST', 1);
-def(ModuleBuilder, 'NESTED_LAST',  2);
-def(ModuleBuilder, 'NESTED_CAMEL', 3);
-
-module.exports = ModuleBuilder;