@lumjs/core 1.38.1 → 1.38.3

package/lib/types/lazy.js

@@ -1,225 +1,18 @@
-const def = require('./def');
-const {S,F} = require('./js');
-const {COMPLEX} = require('./typelist');
-const {needType,needObj} = require('./needs');
-const {doesDescriptor} = require('./basics');
-
-/**
- * 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.
- * 
- * Leave it `undefined` to use the default assignment behaviour.
- * 
- * @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 
- * @param {module:@lumjs/core/types~LazyDef} info - A metadata object
- * @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} The `info` 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.
- */
+const {deprecated} = require('../meta');
+const {lazy} = require('../obj/df');
 
 /**
  * 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.
- * 
- * IMPORTANT: In a later v1.18.x release, this will be refactored to use the
- * [obj.df()]{@link module:@lumjs/core/obj.df} function that will replace
- * def(). There's already an alias called `df.lazy()` available now.
- * This will also be moved to the `obj` module, with a deprecated alias left
- * in the `types` module for the duration of the 1.x lifecycle.
- *
- * @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
+ * @name module:@lumjs/core/types.lazy
+ * @deprecated Moved to `obj` module; this alias will be removed in v2.x
+ * @see {@link module:@lumjs/core/obj.lazy} for API docs.
  */
-function lazy(target, name, initfunc, opts={})
+module.exports = function (...args)
 {
-  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);
-      // Now return the newly assigned value.
-      return target[name];
-    }
-    else if (doesDescriptor(value))
-    { // A descriptor was returned, extract the real value.
-      if (typeof value.get === F)
-      {
-        return value.get();
-      }
-      else 
-      {
-        return value.value;
-      }
-    }
-    else 
-    { // Just return the original value.
-      return value;
-    }
-  }
-
-  desc.get = function()
-  { 
-    return defval(initfunc.call(context,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.
-  return def(target, name, desc);
+  const retval = lazy(...args);
+  return deprecated(
+    'core.types.def.lazy',
+    'core.obj.lazy',
+    retval
+  );
 }
-
-// Gotta be one of the greatest lines...
-def(def, 'lazy', lazy);
-
-// And this is a close second...
-def(lazy, 'def', def);
-
-module.exports = lazy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.38.1",
+  "version": "1.38.3",
   "main": "lib/index.js",
   "exports": 
   {
@@ -31,7 +31,8 @@
   },
   "dependencies": 
   {
-    "@lumjs/opts": "^1.0.0"
+    "@lumjs/opts": "^1.0.0",
+    "@lumjs/events-observable": "^1.0.1"
   },
   "devDependencies": 
   {

package/lib/events/event.js

@@ -1,89 +0,0 @@
-"use strict";
-
-const {SY,F,isObj} = require('../types');
-
-/**
- * An Event object to emit to handler callbacks.
- * 
- * @prop {module:@lumjs/core/events.Listener} eventListener
- * The event Listener instance this event was emitted from.
- * @prop {(string|Symbol)} type - The event type that was triggered.
- * @prop {string} name - The event name that was triggered;
- * if `type` is a string this will be the same value,
- * for a Symbol type this will be the `type.description` value.
- * @prop {object} target - Target object for this event.
- * @prop {Array} args - Arguments passed to `emit()`
- * @prop {object} options - Composes options from the
- * Registry and the Listener. Listener options take priority.
- * @prop {?object} data 
- * If `args[0]` is any kind of `object` other than another Event 
- * instance, it will be used as the `data` property. 
- * If `args[0]` is not an `object`, this property will be `null`.
- * @prop {module:@lumjs/core/events.Event} origEvent
- * Unless `this.prevEvent` is set, this should always be
- * a reference to `this` instance itself.
- * @prop {?module:@lumjs/core/events.Event} prevEvent
- * If `args[0]` is another Event instance this property
- * will be set with its value, as well as the following
- * changes to the default behavior:
- * 
- * - `this.data` will be set to `prevEvent.data`.
- * - `this.origEvent` will be set to `prevEvent.origEvent`
- * 
- * @prop {module:@lumjs/core/events~Status} emitStatus
- * 
- * @alias module:@lumjs/core/events.Event
- */
-class LumEvent 
-{
-  /**
-   * Create a new Event instance; should not be called directly.
-   * @protected
-   * @param {module:@lumjs/core/events.Listener} listener 
-   * @param {object} target 
-   * @param {(string|Symbol)} type 
-   * @param {Array} args 
-   * @param {object} status
-   */
-  constructor(listener, target, type, args, status)
-  {
-    const reg = listener.registry;
-    this.eventListener = listener;
-    this.args = args;
-    this.target = target;
-    this.type = type;
-    this.name = (typeof type === SY) ? type.description : type;
-    this.emitStatus = status;
-    this.options = Object.assign({},
-      reg.options,
-      listener.options,
-      status.options);
-
-    this.data = null;
-    this.prevEvent = null;
-    this.origEvent = this;
-
-    if (isObj(args[0]))
-    { // The first argument is an object.
-      const ao = args[0];
-      if (ao instanceof LumEvent)
-      { // A previous event.
-        this.prevEvent = ao;
-        this.origEvent = ao.origEvent;
-        this.data      = ao.data;
-      }
-      else
-      { // Use it as a data object.
-        this.data = ao;
-      }
-    }
-
-    if (typeof this.options.setupEvent === F)
-    {
-      this.options.setupEvent.call(listener, this);
-    }
-
-  }
-}
-
-module.exports = LumEvent;

package/lib/events/listener.js

@@ -1,139 +0,0 @@
-"use strict";
-
-const {F,isObj} = require('../types');
-const Event = require('./event');
-
-const REMOVE_OPTS = ['listener','handler','eventNames','eventTypes'];
-
-function makeOpts(spec)
-{
-  const opts = Object.assign({}, spec, spec.options);
-  for (const rm of REMOVE_OPTS)
-  {
-    delete opts[rm];
-  }
-  return opts;
-}
-
-/**
- * Is something a valid value for an event listener?
- * 
- * Valid listener values are inspired by the `DOM.EventTarget` interface:
- * 
- * - A `function`
- * - An `object` with a `handleEvent()` method
- * 
- * @param {*} v - Value we are testing
- * @returns {boolean}
- * @alias module:@lumjs/core/events.Listener.isListener
- */
-function isListener(v)
-{
-  return (typeof v === F || (isObj(v) && typeof v.handleEvent === F));
-}
-
-/**
- * An Event Listener instance used by a Registry
- * 
- * Used internally by the Registry class, there's likely very few 
- * reasons you'd want to call any methods on this manually.
- * 
- * @prop {module:@lumjs/core/events.Registry} registry 
- * The Registry instance this Listener belongs to.
- * @prop {(function|object)} handler - Event handler callback
- * @prop {Set} eventTypes - A set of all event types handled by this
- * @prop {Set} eventNames - Alias to `eventTypes`
- * @prop {object} options - Options specific to this listener.
- * 
- * See {@link module:@lumjs/core/events.Registry#makeListener makeListener()}
- * for details on what this may contain and how it is populated.
- * 
- * @alias module:@lumjs/core/events.Listener
- */
-class LumEventListener
-{
-  /**
-   * Build a listener; called by Registry instance
-   * @private
-   * @param {module:@lumjs/core/events.Registry} registry 
-   * @param {object} spec 
-   */
-  constructor(registry, spec)
-  {
-    if (isListener(spec.listener))
-    {
-      this.handler = spec.listener;
-    }
-    else if (isListener(spec.handler))
-    {
-      this.handler = spec.handler;
-    }
-    else
-    {
-      console.error({spec,registry});
-      throw new TypeError("Invalid listener/handler in spec");
-    }
-    
-    // Assign the rest here.
-    this.registry = registry;
-    this.options = makeOpts(spec);
-    const events = spec.eventTypes ?? spec.eventNames;
-    this.eventTypes = this.eventNames = registry.getEventNames(events);
-
-    const setup = this.options.setupListener ?? registry.options.setupListener;
-    if (typeof setup === F)
-    {
-      setup.call(registry, this);
-    }
-  }
-
-  /**
-   * See if there is at least one item in `this.eventTypes`
-   * @type {boolean}
-   */
-  get hasEvents()
-  {
-    return this.eventTypes.size > 0;
-  }
-
-  /**
-   * Used by {@link module:@lumjs/core/events.Registry#emit emit()} to create
-   * and emit a new Event instance for a specified event name and target.
-   * 
-   * This is a *protected method* and should not be called directly.
-   * @protected
-   * @param {string} type      - A single event type/name that was triggered
-   * @param {object} target    - A single target object
-   * @param {Array}  args      - Arguments passed to `emit()`
-   * @param {module:@lumjs/core/events~Status} status - Emit status info
-   * @returns {module:@lumjs/core/events.Event} The new Event that was emitted
-   */
-  emitEvent(type, target, args, status)
-  {
-    const event = new Event(this, target, type, args, status);
-
-    if (typeof this.handler === F)
-    { // The simplest is the good old function
-      this.handler.call(event.target, event);
-    }
-    else
-    { // An object with a `handleEvent()` method
-      this.handler.handleEvent(event);
-    }
-
-    if (event.options.once)
-    { // This listener is to be removed
-      status.onceRemoved.add(this);
-    }
-
-    return event;
-  }
-
-  static get classProps()
-  {
-    return Object.getOwnPropertyNames(this.prototype);
-  }
-}
-
-LumEventListener.isListener = isListener;
-module.exports = LumEventListener;