@lumjs/core 1.3.1 → 1.4.0

package/docs/changelogs/1.x.md

@@ -6,6 +6,13 @@ See [Changelogs](index.md) for more information on the changelogs.
 
 ## [Unreleased]
 
+## [1.4.0] - 2022-09-26
+### Changed
+- Moved `lazy` into `types` module by default (leaving an alias in `core`).
+- Completely rewrote the `lazy` function entirely.
+- Greatly extended the documentation for `lazy` function.
+- Removed an unused development artefact from `types.needs`.
+
 ## [1.3.1] - 2022-09-23
 ### Fixed
 - The `arrays` module exports `powerset` and `random` as it should.
@@ -74,7 +81,8 @@ See [Changelogs](index.md) for more information on the changelogs.
 - See [1.0-beta.md](1.0-beta.md) for the beta versions of `1.0`
 - See [lum.js](https://github.com/supernovus/lum.js) for the original library set this is replacing.
 
-[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/supernovus/lum.core.js/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/supernovus/lum.core.js/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/supernovus/lum.core.js/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/supernovus/lum.core.js/compare/v1.2.0...v1.2.1

package/lib/index.js

@@ -112,9 +112,6 @@ const Enum = require('./enum');
  */
 const observable = require('./observable');
 
-// One function exported directly with no sub-module available.
-const lazy = require('./lazy');
-
 /**
  * Define properties on an object or function.
  * @alias module:@lumjs/core.def
@@ -123,6 +120,14 @@ const lazy = require('./lazy');
  */
 const def = types.def;
 
+/**
+ * Define properties on an object or function.
+ * @alias module:@lumjs/core.lazy
+ * @function
+ * @see module:@lumjs/core/types.lazy
+ */
+ const lazy = types.lazy;
+
 module.exports =
 {
   types, context, flags, obj, opt, modules, arrays, strings,

package/lib/types/index.js

@@ -39,6 +39,7 @@ const {needObj, needType, needs} = require('./needs');
 // A few standalone items.
 
 const def   = require('./def');
+const lazy  = require('./lazy');
 const TYPES = require('./typelist');
 const stringify = require('./stringify');
 
@@ -46,7 +47,7 @@ const stringify = require('./stringify');
 // Further tests can be added by `TYPES.add()` later.
 module.exports =
 {
-  O, F, S, B, N, U, SY, BI, TYPES, root, unbound, def,
+  O, F, S, B, N, U, SY, BI, TYPES, root, unbound, def, lazy,
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
   isInstance, isType, isa, needObj, needType, needs, stringify,

package/lib/types/lazy.js

@@ -0,0 +1,196 @@
+const def = require('./def');
+const {S,F} = require('./js');
+const {COMPLEX} = require('./typelist');
+const {needType,needObj} = require('./needs');
+
+/**
+ * Metadata for the property definition.
+ * 
+ * @typedef module:@lumjs/core/types~LazyDef
+ * @property {string} name - The `name` passed to `lazy()`
+ * @property {(object|function)} target - The `target` passed to `lazy()`
+ * @property {object} opts - The `opts` passed to `lazy()`
+ * @property {object} arguments - The full `arguments` passed to `lazy()`
+ * 
+ * @property {boolean} [assign] Override default assignment rules?
+ * 
+ * This property may be added by the `LazyGetter` or `LazySetter` 
+ * functions to override the default assignment rules. 
+ * 
+ * If this is `true` the return value will be assigned, replacing the 
+ * lazy accessor property, even if the value is `undefined`.
+ * 
+ * If this is `false`, the value will be returned, but will **not** be 
+ * *assigned*, so the lazy accessor property will remain.
+ * 
+ * @property {*} [def] Special options for `def()`
+ * 
+ * The [def()]{@link module:@lumjs/core/types.def} function has an
+ * optional fourth parameter called `opts` which is used for a few
+ * specialized purposes. If this property is set, it will be used as
+ * the value for `opts` when assigning the return value to the property.
+ * 
+ * Leave it `undefined` to use the default `def()` behaviour.
+ * 
+ */
+
+/**
+ * A function to generate the property value.
+ * 
+ * @callback module:@lumjs/core/types~LazyGetter 
+ * @returns {*} The generated *value* of the property
+ * 
+ * By default if this is `undefined` the value will **not** be
+ * assigned, and instead the accessor property will remain in
+ * place to be used on subsequent calls until a value other than
+ * `undefined` is returned.
+ * 
+ * This assignment behaviour can be overridden by the function
+ * if it sets `this.assign` to an explicit boolean value.
+ * 
+ * As we are using [def()]{@link module:@lumjs/core/types.def} 
+ * to assign the value, by default if the return value appears 
+ * to be a valid *Descriptor* object, it will be used as the 
+ * property descriptor. See `def()` for further details on how
+ * it handles the various arguments.
+ * 
+ * Regardless of the value of `this.assign`, this value will
+ * be *returned* as the property value.
+ * 
+ * @this {module:@lumjs/core/types~LazyDef} A metadata object.
+ */
+
+/**
+ * A function to handle attempts at assignment.
+ * 
+ * Very similar to [LazyGetter]{@link module:@lumjs/core/types~LazyGetter}
+ * but called when property assignment is attempted on the
+ * lazy accessor property.
+ * 
+ * If you explicitly want to forbid assignment, you can throw
+ * an `Error` from this function.
+ * 
+ * @callback module:@lumjs/core/types~LazySetter
+ * @param {*} value - The value attempting to be assigned.
+ * @returns {*} The *actual* assignment value (if any.)
+ * 
+ * The same assignment rules apply as in the
+ * [LazyGetter]{@link module:@lumjs/core/types~LazyGetter}
+ * callback.
+ * 
+ * @this {module:@lumjs/core/types~LazyDef} A metadata object.
+ */
+
+/**
+ * Build a lazy initializer property.
+ * 
+ * This builds an *accessor* property that will replace itself
+ * with a initialized property, the value of which is obtained from
+ * a supplied initialization function. Any subsequent use of the
+ * property will obviously be using the initialized property directly.
+ * 
+ * The general purpose is if there is a property that requires
+ * a fairly intensive load time, or requires a large library that
+ * you may not always *need* for basic things, you can use this
+ * to ensure that the property is only initialized when needed.
+ * 
+ * This is an extension of the [def()]{@link module:@lumjs/core/types.def} 
+ * method, and indeed an alias called `def.lazy()` is also available.
+ *
+ * @param {(object|function)} target - The object to add the property to.
+ * 
+ * As with `def()` itself, this can be either an `object` or `function`,
+ * as in Javascript the latter is an extension of the former.
+ * 
+ * @param {string} name - The name of the property to add.
+ * 
+ * @param {module:@lumjs/core/types~LazyGetter} initfunc 
+ * The function to initialize the property.
+ * 
+ * This will normally only ever be called the first time the property
+ * is accessed in a *read* operation. The return value from this
+ * will be assigned to the property using `def()`, replacing the
+ * lazy accessor property.
+ * 
+ * @param {object} [opts] Options to customize behavior.
+ * 
+ * @param {module:@lumjs/core/types~LazySetter} [opts.set]
+ * A function to handle assignment attempts.
+ * 
+ * This obviously only applies to the *lazy accessor* property,
+ * and will have no affect once the property has been replaced
+ * by its initialized value.
+ * 
+ * @param {boolean} [opts.enumerable=false] Is the property enumerable?
+ * 
+ * This applies to the *lazy accessor* property only.
+ * You can set custom descriptor rules in the `initfunc`
+ * if you need them on the initialized property.
+ * 
+ * @param {?boolean} [opts.assign] The *default* value for the `assign` property
+ * in the [LazyDef]{@link module:@lumjs/core/types~LazyDef} object.
+ * 
+ * @param {*} [opts.def] The *default* value for the `def` property in
+ * the [LazyDef]{@link module:@lumjs/core/types~LazyDef} object.
+ *
+ * @returns {(object|function)} The `target` argument
+ * 
+ * @alias module:@lumjs/core/types.lazy
+ */
+function lazy(target, name, initfunc, opts={})
+{
+  needType(COMPLEX, target, 'obj must be an object');
+  needType(S, name, 'name must be a string');
+  needType(F, initfunc, 'initfunc must be a function');
+  needObj(opts, 'opts parameter was not an object');
+
+  // The `this` object for the functions.
+  const context = 
+  { 
+    name, 
+    target, 
+    opts, 
+    arguments,
+    assign: opts.assign,
+    def: opts.def,
+  }
+
+  // The descriptor for the lazy accessor.
+  const desc = 
+  {
+    configurable: true, 
+    enumerable: opts.enumerable ?? false,
+  };
+
+  // Replace the property if rules are correct.
+  const defval = function(value)
+  {
+    const assign = (context.assign ?? value !== undefined);
+    if (assign)
+    { // Replace the lazy accessor with the returned value.
+      def(target, name, value, context.def);
+    }
+    return value;
+  }
+
+  desc.get = function()
+  { 
+    return defval(initfunc.call(context));
+  }
+
+  if (typeof opts.set === F)
+  { // We want to assign a lazy setter as well.
+    desc.set = function(value)
+    {
+      defval(opts.set.call(context, value));
+    }
+  }
+
+  // Assign the lazy accessor property.
+  def(target, name, desc);
+}
+
+// Gotta be one of the greatest lines...
+def(def, 'lazy', lazy);
+
+module.exports = lazy;

package/lib/types/needs.js

@@ -59,15 +59,6 @@ function needType (type, v, msg, unused)
 }
 
 exports.needType = needType;
-
-// Options parser for needs();
-const NEEDS_PARSER = function(type, v)
-{ // `this` is the options object itself.
-  if (typeof type.is === F)
-  { // We assume `is()` methods are the type check.
-    if (type.is(v)) return true;
-  }
-}
  
 /**
 * A wrapper around `isa()` that will throw an error on failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "main": "lib/index.js",
   "exports":
   {

package/lib/lazy.js

@@ -1,100 +0,0 @@
-
-const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
-
-/**
- * @callback module:@lumjs/core~InitFunc 
- * @param {string} name - The `name` parameter passed to `lazy()`
- * @this {object} - The `obj` parameter passed to `lazy()`
- */
-
-/**
- * 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 def} method, and indeed an
- * alias called `def.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 {module:@lumjs/core~InitFunc} initfunc 
- *   The function to initialize the property.
- * @param {*} [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={}] Descriptor rules for the property.
- *   We only support two descriptor rules with this function, and
- *   their default values are the same as the `def()` function.
- *   - `configurable` → `true`
- *   - `enumerable` → `false`
- *   Any other descriptor properties are invalid here.
- *
- * @return {Object} The object we defined the property on.
- * @alias module:@lumjs/core.lazy
- */
-function lazy(obj, name, initfunc, onset, desc={})
-{
-  needType(COMPLEX, obj, 'obj must be an object');
-  needType(S, name, 'name must be a string');
-  needType(F, initfunc, 'initfunc must be a function');
-  needObj(desc, 'desc parameter was not an object');
-
-  let value;
-
-  desc.get = function()
-  {
-    if (value === undefined)
-    {
-      value = initfunc.call(this, name);
-    }
-    return value;
-  }
-
-  if (onset === true)
-  { // Allow direct assignment.
-    desc.set = function(newval)
-    {
-      value = newval;
-    }
-  }
-  else if (onset === false)
-  { // Throw an error on assignment.
-    desc.set = function()
-    {
-      throw new ReferenceError("The "+name+" property is read-only");
-    }
-  }
-  else if (typeof onset === F)
-  { // A proxy method for assignment.
-    desc.set = function(newval)
-    {
-      const setval = onset.call(this, newval, value);
-      if (setval !== undefined)
-      {
-        value = setval;
-      }
-    }
-  }
-
-  def(obj, name, desc);
-}
-
-// Gotta be one of the greatest lines...
-def(def, 'lazy', lazy);
-
-module.exports = lazy;