@lumjs/compat 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2022-10-13
+### Changed
+- Bumped `@lumjs/core` to `1.6.1`.
+- Rewrote `v4/index` to use `core.buildModule()` and lazy-loading.
+
+## [1.2.0] - 2022-09-12
+### Changed
+- Updated almost all of the DocBlocks for better documentation.
+- Updated README for similar reasons.
+- Changed `v4/meta` into a top-level `v4` that includes all sub-modules.
+- Bumped `@lumjs/core` dependency version to latest.
+### Fixed
+- Fixed a bug in the *default* module.
+
 ## [1.1.0] - 2022-08-11
 ### Changed
 - Moved all *v4* stuff into a new `v4` sub-module.
@@ -20,7 +34,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.1.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v1.3.0...HEAD
+[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
 [1.1.0]: https://github.com/supernovus/lum.compat.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.compat.js/releases/tag/v1.0.0
 

package/README.md

@@ -23,22 +23,19 @@ exported from this library.
 
 The main entrypoint is reserved for generic compatibility functions.
 
-### `@lumjs/compat/v4-meta`
+### `@lumjs/compat/v4`
 
-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.
+The `v4` compatibility namespace. Includes all `v4` modules in one simple object.
 
-| Core Property   | Description                                               |
+| 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.
+| `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.                           |
 
 ## Official URLs
 

package/lib/index.js

@@ -9,7 +9,7 @@ class Package
   constructor(pkg)
   { 
     this.file = pkg+'/'+PKGJSON;
-    this.info = require(this.conf);
+    this.info = require(this.file);
     this.version = semver.parse(this.info.version);
   }
 

package/lib/v4/descriptors.js

@@ -1,6 +1,11 @@
+/**
+ * Descriptors magic objects library.
+ * @module @lumjs/compat/v4/descriptors
+ */
+
 const core = require('@lumjs/core');
 const {InternalObjectId,Enum,types} = core;
-const {doesDescriptor,isObj,isComplex,def,B,F,N} = types;
+const {doesDescriptor,isObj,def,B,F,N} = types;
 
 // We moved getProperty() to the `@lumjs/core/obj` module.
 const getProperty = core.obj.getProperty;
@@ -14,6 +19,7 @@ const DESC_ADD = Enum(['ONE', 'SHORT', 'SET'], {flags: true});
  * @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={})
 {
@@ -177,6 +183,7 @@ 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)
 {
@@ -187,6 +194,7 @@ exports.getDescriptor = getDescriptor;
 
 /**
  * A factory for building magic Descriptor objects.
+ * @alias module:@lumjs/compat/v4/descriptors.DESC
  */
 const DESC =
 {
@@ -207,4 +215,3 @@ def(DESC)
   ('ADD',  DESC_ADD);
 
 exports.DESC = DESC;
-

package/lib/v4/index.js

@@ -0,0 +1,58 @@
+/**
+ * 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');
+//exports.descriptors = require('./descriptors');
+
+/**
+ * @name module:@lumjs/compat/v4.DESC
+ * @see module:@lumjs/compat/v4/descriptors.DESC
+ */
+from('descriptors', true, 'DESC');
+//exports.DESC = exports.descriptors.DESC;
+
+/**
+ * @name module:@lumjs/compat/v4.prop
+ * @see module:@lumjs/compat/v4/prop
+ */
+can('prop');
+//exports.prop = require('./prop');
+
+/**
+ * @name module:@lumjs/compat/v4.deprecated
+ * @see module:@lumjs/compat/v4/deprecated
+ */
+can('deprecated');
+//exports.deprecated = require('./deprecated');
+
+/**
+ * @name module:@lumjs/compat/v4.LoadTracker
+ * @see module:@lumjs/compat/v4/loadtracker
+ */
+can('LoadTracker', {module: './loadtracker'});
+//exports.LoadTracker = require('./loadtracker');
+
+/**
+ * @name module:@lumjs/compat/v4.Promise
+ * @see module:@lumjs/compat/v4/promise
+ */
+can('Promise', {module: './promise'});
+//exports.Promise = require('./promise');
+
+/**
+ * @name module:@lumjs/compat/v4.obj
+ * @see module:@lumjs/compat/v4/object-helpers
+ */
+can('obj', {module: './object-helpers'});
+//exports.obj = require('./object-helpers');

package/lib/v4/loadtracker.js

@@ -13,7 +13,7 @@ const {F,S,B,needObj,needType,def} = core.types
  * test which simply see's if the `loadTracker.mark()`
  * method has been called for the specified name.
  * 
- * @class Lum.LoadTracker
+ * @exports module:@lumjs/compat/v4/loadtracker
  */
 class LoadTracker
 {

package/lib/v4/object-helpers.js

@@ -1,3 +1,8 @@
+/**
+ * Object helpers module
+ * @module @lumjs/compat/v4/object-helpers
+ */
+
 const core = require('@lumjs/core');
 const {O,F,S,B,isObj} = core.types;
 const {clone,copyProps} = core.obj;
@@ -18,8 +23,6 @@ const {clone,copyProps} = core.obj;
  * @param {...*} sources - The source traits we want to mix in.
  *
  * @return {object|function}  The `target` will be returned.
- *
- * @alias module:@lumjs/compat/v4/object-helpers.mixin
  */
 exports.mixin = function (target, ...inSources)
 {
@@ -94,8 +97,6 @@ exports.mixin = function (target, ...inSources)
  * Anything else will be invalid and will throw an Error.
  *
  * @return {object|function}  The `target` will be returned.
- *
- * @method Lum.obj.into
  */
 exports.into = function (target, ...sources)
 {
@@ -151,26 +152,28 @@ exports.into = function (target, ...sources)
 }
 
 /**
- * Clone a simple object, using the {@link Lum._.clone} function.
+ * Clone a simple object, using the `@lumjs/core/obj.clone` function.
  *
- * By default it uses `Lum._.CLONE.JSON` mode for cloning, but this can
+ * By default it uses `CLONE.JSON` mode for cloning, but this can
  * be adjusted as desired by passing a `cloneOpts.mode` option.
  *
  * Can also clone extended properties that aren't serialized in JSON.
  *
  * @param {object} object The object or function to clone.
  *
- * @param {object} [copyProperties] Use {@link Lum.copyProperties} as well.
+ * @param {(boolean|object)} [copyProperties] Use `copyProps()` as well.
  *
- *   If copyProperties is defined, and is a non-false value, then we'll
- *   call {@link Lum.obj.copy} after cloning to copy 'special' properties.
+ *   After the regular cloning process, call `@lumjs/core/obj.copyProps()`.
+ *   If this is an `object`, then it's the options for `copyProps()`.
+ *   In the current codebase, this value is assigned as `cloneOpts.copy` as
+ *   the actual code to call `copyProps()` was moved to the upstream core
+ *   `clone()` function a while ago.
  *
- * @param {object} [cloneOpts] Options to send to {@link Lum._clone}
+ * @param {object} [cloneOpts] Options for the core `clone()`.
  *
- *   This can be any options supported by the {@link Lum._.clone} function.
+ *   This can be any options supported by the core `clone()` function.
  *
  * @return {object}  A clone of the object.
- *
  */
 exports.clone = function(object, copyProperties, cloneOpts)
 {

package/lib/v4/promise.js

@@ -1,20 +1,24 @@
 const {B,O,F} = require('@lumjs/core').types;
 
 /**
- * @class LumPromise
+ * Build a *Promise* object with *Deferred* compatibility.
  *
- * Build the Promise object.
+ * @param {(object|boolean)} [options] Options for the `Promise` object.
  *
- * @param (object|boolean) options Options for the Promise object.
+ *  If options is a `boolean`, it's assumed to be the `jquery` option.
+ * 
+ * @param {boolean} [options.jquery] Use `jQuery.Deferred` API?
+ * - If `true`, use `this._extendJQuery(options)` to define methods.
+ * - If `false`, use `this._extendInternal(options)` to define methods.
  *
- *  If options is a boolean, it's assumed to be the 'jquery' option.
- *
- *  Recognized properties if options is an object:
- *
- *   jquery: (boolean)  If true, run this._extendJQuery(options);
- *                      If false, run this._extendInternal(options);
- *
- * @deprecated Use HTML 5 Promises, or the jQuery.Deferred API directly.
+ * @exports module:@lumjs/compat/v4/promise
+ * @deprecated Use the Javascript `Promise` object directly.
+ * 
+ * If you need compatibility with the `jQuery.Deferred` API,
+ * just use the `jQuery.Deferred` API itself.
+ * 
+ * If you need the `deferDone` or `deferFail` methods, use
+ * this until the `@lumjs/defer` library is released.
  */
 function LumPromise(options)
 {
@@ -43,6 +47,8 @@ const lpp = LumPromise.prototype;
  * Add the methods from jQuery.Deferred to ourself.
  *
  * If jQuery is not loaded, this will throw an error.
+ * 
+ * @alias module:@lumjs/compat/v4/promise#_extendJQuery
  */
 lpp._extendJQuery = function (options)
 {
@@ -66,6 +72,7 @@ lpp._extendJQuery = function (options)
  *  Targetted triggers:  resolveWith(), rejectWith(), notifyWith()
  *  Info:                state()
  *
+ * @alias module:@lumjs/compat/v4/promise#_extendInternal
  */
 lpp._extendInternal = function (options)
 {
@@ -334,7 +341,7 @@ lpp._extendInternal = function (options)
   {
     return state;
   }
-}
+} // _extendInternal()
 
 /**
  * Execute a delayed 'done' action.
@@ -343,6 +350,8 @@ lpp._extendInternal = function (options)
  * @param str    ts       The textStatus to send to done().
  * @param mixed  xhr      Object to use as XHR (default is this.)
  * @param int    timeout  The timeout (in ms) defaults to 5.
+ * 
+ * @alias module:@lumjs/compat/v4/promise#deferDone
  */
 lpp.deferDone = function (obj, ts, xhr, timeout)
 {
@@ -364,6 +373,8 @@ lpp.deferDone = function (obj, ts, xhr, timeout)
  * @param str    ts       The textStatus to send to fail().
  * @param mixed  xhr      Object to use as XHR (default is this.)
  * @param int    timeout  The timeout (in ms) defaults to 5.
+ * 
+ * @alias module:@lumjs/compat/v4/promise#deferFail
  */
 lpp.deferFail = function (error, ts, xhr, timeout)
 {

package/lib/v4/prop.js

@@ -74,7 +74,7 @@ const {DESC,getDescriptor} = require('./descriptors');
  *   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
+ * @exports module:@lumjs/compat/v4/prop
  * @deprecated Replaced by `@lumjs/core.def` method. 
  */
 function prop(obj, name, arg1, arg2, arg3)

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@lumjs/compat",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
-    "./v4-meta": "./lib/v4/meta.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"
   },
@@ -14,7 +16,7 @@
     "url": "https://github.com/supernovus/lum.compat.js.git"
   },
   "dependencies": {
-    "@lumjs/core": "^1.1.0",
+    "@lumjs/core": "^1.6.1",
     "semver": "^7.3.7"
   },
   "scripts":

package/lib/v4/meta.js

@@ -1,14 +0,0 @@
-/**
- * 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');