@lumjs/core 1.0.0-beta.4 → 1.1.0

package/README.md

@@ -8,12 +8,16 @@ Used by all the rest of my *Lum.js* libraries.
 
 ## Documentation
 
-I am working on fleshing out the documentation in `jsdoc3` format.
-You can compile the unfinished version using `jsdoc -c ./jsdoc.json` 
+### [API Docs](https://supernovus.github.io/docs/js/@lumjs/core/)
+
+The documentation is written in [JSDoc 3](https://jsdoc.app/) format.
+
+You can compile the documentation using `npm run build-docs`
 which will put the generated docs into the `./docs/api` folder.
 
-### [Changelog](CHANGELOG.md)
+### [Changelog](./docs/changelogs/1.x.md)
 ### [TODO](TODO.md)
+### [Homepage](https://supernovus.github.io/)
 
 ## Official URLs
 

package/TODO.md

@@ -1,16 +1,15 @@
 # TODO
 
-## 1.0.0 Release
-
 - Proper tests using new [@lumjs/tests](https://github.com/supernovus/lum.tests.js) library.
   - [x] `types/js`
   - [x] `types/basics` 
   - [x] `types/root`
-  - [ ] `types/isa`
-  - [ ] `types/needs`
-  - [ ] `types/def`
-  - [ ] `types/typelist`
-  - [ ] `types/index`
+  - [x] `types/isa`
+  - [x] `types/needs`
+  - [x] `types/def`
+  - [x] `types/typelist`
+  - [ ] `types/stringify`
+  - [x] `types/index`
   - [x] `arrays`
   - [ ] `context`
   - [ ] `strings`
@@ -29,9 +28,4 @@
   - [ ] `lazy`
   - [ ] `observable`
   - [ ] `index`
-- Finish the documentation marked as *TODO*.
-- Create new `Changelog-1.x.md` and make it the active `CHANGELOG.md` link.
-
-## Future
 
-- Who knows, further work on this can wait until the rest of the libraries are finished.

package/docs/changelogs/1.0-beta.md

@@ -4,7 +4,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## Note
+
+This is the *Changelog* for the `1.0.0-beta.x` releases.
+See [1.x.md](1.x.md) for the stable `1.x` *Changelog*.
+
+## [1.0.0-beta.6]
+- This is the **final** beta version. 
+- Version `1.0.0` will be this but with the docs updated a bit.
+### Added
+- More tests for the `types` module.
+- Changelog file for the upcoming `1.x` *stable* releases.
+### Changed
+- Removed some convoluted options from `def()`.
+- Reworked `types.stringify()` to handle recursive mode better.
+- Added `Error` stringification to `types.stringify()`
+
+## [1.0.0-beta.5] - 2022-07-18
+### Added
+- A new `types.stringify()` method.
+- Shortcut `string` options for the `types.def()` method.
+- A `build-docs` script in `package.json`.
+### Changed
+- Overhauled all DocBlocks to conform to `JSDoc 3` format.
+- Changed `context.has` to support a magic `Proxy` version.
+- Some tweaks to `Enum` to cleanup some things.
+- Both `Enum` and `observable` use `TYPES.add()` now.
+- In `modules.name()` nixed `opts.noAuto` and added `opts.useAuto` instead.
+- Created explicit `exports` definition in `package.json` with our sub-modules.
+### Fixed
+- Fixed a property definition issue in `obj.SOA()`. 
 
 ## [1.0.0-beta.4] - 2022-07-15
 ### Added
@@ -35,7 +64,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated `obj/clone` and `obj/lock` to remove use of `descriptors` magic.
 - Updated `CLONE` mode documentation to use a table format.
 - A few minor tweaks and cleanups related to the rest of the above changes.
-- Updated [TODO.md](TODO.md) with the plans for the final `1.0.0` release.
+- Updated [../../TODO.md](TODO.md) with the plans for the final `1.0.0` release.
 
 ## [1.0.0-beta.3] - 2022-07-11
 ### Added
@@ -61,7 +90,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Pulled a bunch of the core libraries from the old Lum.js project.
 - Refactored and reorganized the libraries a lot.
 
-[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.4...HEAD
+[1.0.0-beta.6]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.5...v1.0.0-beta.6
+[1.0.0-beta.5]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.4...v1.0.0-beta.5
 [1.0.0-beta.4]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.3...v1.0.0-beta.4
 [1.0.0-beta.3]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.2...v1.0.0-beta.3
 [1.0.0-beta.2]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.1...v1.0.0-beta.2

package/docs/changelogs/1.x.md

@@ -0,0 +1,32 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2022-07-29
+### Added
+- `types.doesDescriptorTemplate()` method.
+- `obj.getProperty()` method (used to be in the `descriptors` sub-module.)
+### Changed
+- Tweaked documentation for:
+  - `obj.getObjectPath()`
+  - `obj.setObjectPath()`
+  - `obj.getNamespace()`
+  - `obj.setNamespace()`
+- Updated error messages in `obj.setObjectPath()`
+- Made `obj.setObjectPath()` use `types.doesDescriptorTemplate()` for validation of `opts.desc` option.
+- Changed `obj.getObjectPath()` and `obj.setObjectPath()` to support `function` parent objects.
+- Enhanced `types.stringify()` to support `RegExp` as well as supporting custom extensions down the road.
+
+## [1.0.0] - 2022-07-27
+### Changed
+- Initial *stable* release.
+- 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 this is replacing.
+
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/supernovus/lum.core.js/releases/tag/v1.0.0
+

package/lib/arrays.js

@@ -1,8 +1,14 @@
+/**
+ * Array helper functions.
+ * @module @lumjs/core/arrays
+ */
+
 /** 
  * See if an array contains *any* of the specified items.
  * @param {Array} array 
  * @param  {...any} items 
  * @returns {boolean}
+ * @alias module:@lumjs/core/arrays.containsAny
  */
  function containsAny(array, ...items)
  {
@@ -22,9 +28,10 @@
 
  /**
   * See if an array contains *all* of the specified items.
-  * @param {Array} array 
+  * @param {Array} array
   * @param  {...any} items 
   * @returns {boolean}
+  * @alias module:@lumjs/core/arrays.containsAll
   */
  function containsAll(array, ...items)
  {
@@ -43,11 +50,16 @@
  exports.containsAll = containsAll;
  
 /**
-* Remove items from an array.
-* @param {Array} array 
-* @param  {...any} items 
-* @returns {number} Number of items removed.
-*/
+ * Remove items from an array.
+ * 
+ * Passed any number of items, it will see if any of those items are
+ * found in the array, and if they are, will remove them from the array.
+ * 
+ * @param {Array} array 
+ * @param  {...any} items 
+ * @returns {number} Number of items actually removed.
+ * @alias module:@lumjs/core/arrays.removeItems
+ */
 function removeItems(array, ...items)
 {
   let removed = 0;
@@ -63,4 +75,4 @@ function removeItems(array, ...items)
   return removed;
 }
 
-exports.removeItems = removeItems;
+exports.removeItems = removeItems;

package/lib/context.js

@@ -1,15 +1,28 @@
 
-const {root,B,F,U,O,isObj,isComplex,def} = require('./types');
-
 /**
- * Context object.
- * 
- * @namespace Lum.context
+ * Context sub-module
  * 
- * Offers some insight into the current JS context.
+ * Used as a static object that has a bunch of properties
+ * describing the current JS environment and execution context.
  * 
+ * @module @lumjs/core/context
+ * @property {boolean} AMD - AMD (*RequireJS*) module loading detected.
+ * @property {boolean} CJS - CommonJS environment detected.
+ * @property {boolean} hasRequire - A global `require()` function was found.
+ * @property {boolean} hasExports - A global `exports` object was found.
+ * @property {boolean} hasModule - A global `module` object was found.
+ * @property {boolean} isNode - Is likely *Node.js*, *Electron*, etc.
+ * @property {boolean} isBrowser - A web-browser environment detected.
+ * @property {boolean} isWindow - Is a browser `Window` context.
+ * @property {boolean} isWorker - Is a browser `Worker` (sub-types below.)
+ * @property {boolean} isServiceWorker - Is a `ServiceWorker` context.
+ * @property {boolean} isDedicatedWorker - Is a `DedicatedWorker` context.
+ * @property {boolean} isSharedWorker - Is a `SharedWorker` context.
+ * @property {object} root - See {@link module:@lumjs/core/types.root}
  */
 
+const {root,B,F,U,O,isComplex,def} = require('./types');
+
 const ctx = {root};
 
 const rootHas = what => typeof root[what] !== U;
@@ -28,8 +41,20 @@ cd('AMD', typeof define === F && define.amd)
   ('isSharedWorker', !ctx.CJS && rootHas('SharedWorkerGlobalScope'))
   ('isBrowser', ctx.isWindow || ctx.isWorker);
 
-// Does the global object/property exist?
-// Caches the results so we can do `context.has.Thingy` tests.
+/**
+ * See if a root-level name is defined.
+ * 
+ * This adds a `context.has.{name}` boolean property which caches the
+ * result so it can be referred to directly.
+ * 
+ * In any JS environment with the `Proxy` object (which honestly should
+ * be all modern ones), you can simple do `context.has.SomeObject` instead
+ * of `context.has('SomeObject')` and it will do the Right Thing™.
+ * 
+ * @param {string} ns - The global function/class/object we're looking for.
+ * @returns {boolean} If that global name is defined or not.
+ * @alias module:@lumjs/core/context.has
+ */
 function hasRoot(ns)
 {
   if (typeof hasRoot[ns] === B) return hasRoot[ns];
@@ -44,6 +69,18 @@ for (const what of ['Proxy','Promise','Reflect','fetch'])
   hasRoot(what);
 }
 
-cd('has', hasRoot);
+if (hasRoot.Proxy)
+{ // Make a Proxy-wrapped version of `context.has`
+  cd('has', new Proxy(hasRoot, 
+  {
+    get(t, p) { return (typeof t[p] !== U) ? t[p] : t(p) }
+  }));
+  // And include the unwrapped version for good measure.
+  cd('$has', hasRoot);
+}
+else
+{ // No Proxy support, just directly assign `context.has()`
+  cd('has', hasRoot);
+}
 
 module.exports = ctx;

package/lib/enum.js

@@ -1,7 +1,7 @@
-const types = require('./types');
-const {S,def,notNil,isObj,needObj} = types;
+const {S,def,notNil,isObj,needObj,TYPES} = require('./types');
 const {InternalObjectId} = require('./objectid');
 
+// Internal id instances should never be exported.
 const ENUM_ID = new InternalObjectId({name: '$Enum'});
 
 /**
@@ -12,17 +12,12 @@ const ENUM_ID = new InternalObjectId({name: '$Enum'});
  * @param {*} spec - TBD
  * @param {*} [opts] - TBD
  * @returns {object} A magic Enum object.
+ * @exports module:@lumjs/core/enum
  */
 function Enum (spec, opts={})
 {
-  if (!isObj(spec))
-  {
-    throw new TypeError("Enum spec must be an object");
-  }
-  if (!isObj(opts))
-  {
-    throw new TypeError("Enum options must be an object")
-  }
+  needObj(spec, "Enum spec must be an object")
+  needObj(opts, "Enum options must be an object")
 
   const anEnum = ENUM_ID.tag({});
 
@@ -61,7 +56,7 @@ function Enum (spec, opts={})
       const name = spec[i];
       if (typeof name !== S)
       {
-        throw new TypeError("Non-string passed in Lum.Enum object");
+        throw new TypeError("Non-string passed in Enum object");
       }
 
       const val 
@@ -117,10 +112,29 @@ function Enum (spec, opts={})
 
 } // Enum
 
-// Add an is() method.
-def(Enum, 'is', ENUM_ID.isFunction());
+/**
+ * Is a value an *Enum* magic object?
+ * @function module:@lumjs/core/enum.is
+ * @param {*} obj - The expected object/function to test.
+ * @returns {boolean}
+ */
+const isEnum = ENUM_ID.isFunction()
+def(Enum, 'is', isEnum);
 
-// And an isEnum() method to the `types` namespace.
-def(types, 'isEnum', Enum.is);
+/**
+ * Is a value an *Enum* magic object?
+ * @name module:@lumjs/core/types.isEnum
+ * @function
+ * @param {*} v - The value to test.
+ * @returns {boolean}
+ * @see module:@lumjs/core/enum.is
+ */
+
+/**
+ * Extension type for {@link module:@lumjs/core/enum} magic objeccts.
+ * @memberof module:@lumjs/core/types.TYPES
+ * @member {string} ENUM - Is an Enum object?
+ */
+TYPES.add('ENUM', 'enum', isEnum, 'isEnum');
 
 module.exports = Enum;

package/lib/flags.js

@@ -1,4 +1,8 @@
 
+/**
+ * Helper functions for working with binary flags.
+ * @module @lumjs/core/flags
+ */
 const {N} = require('./types');
 
 /**
@@ -7,6 +11,7 @@ const {N} = require('./types');
  * @param {number} flag - An integer representing the flag to add or remove.
  * @param {boolean} [value=true] `true` means add, `false` means remove. 
  * @returns {number} The `flags` with the `flag` added or removed accordingly.
+ * @alias module:@lumjs/core/flags.setFlag
  */
 function setFlag(flags, flag, value=true)
 {
@@ -27,6 +32,7 @@ exports.setFlag = setFlag;
  * Combine an entire set of flags into a single set.
  * @param {...number} flag - Any number of flags you want to add.
  * @returns {number} All the passed flags combined into one set.
+ * @alias module:@lumjs/core/flags.allFlags
  */
 function allFlags()
 {

package/lib/index.js

@@ -1,54 +1,126 @@
-// The core library is made up of a bunch of child modules,
-// as well as some standalone classes and functions.
+/**
+ * Core Library
+ * 
+ * This is the foundation upon which all the rest of my JS libraries
+ * are built. It provides fundamental helper functions and classes.
+ * 
+ * @module @lumjs/core
+ */
 
 /**
  * Constants and functions for basic type checking.
+ * @alias module:@lumjs/core.types
+ * @see module:@lumjs/core/types
  */
 const types = require('./types');
 
 /**
  * Array utility functions.
+ * @alias module:@lumjs/core.arrays
+ * @see module:@lumjs/core/arrays
  */
 const arrays = require('./arrays');
 
 /**
  * Information about the JS context we're running in.
+ * @alias module:@lumjs/core.context
+ * @see module:@lumjs/core/context
  */
 const context = require('./context');
 
 /**
  * Functions for working with strings and locales.
+ * @alias module:@lumjs/core.strings
+ * @see module:@lumjs/core/strings
  */
 const strings = require('./strings');
 
 /**
  * Functions for working with binary flags.
+ * @alias module:@lumjs/core.flags
+ * @see module:@lumjs/core/flags
  */
 const flags = require('./flags');
 
 /**
  * Functions for manipulating objects.
+ * @alis module:@lumjs/core.obj
+ * @see module:@lumjs/core/obj
  */
 const obj = require('./obj');
 
 /**
  * Functions for getting values and properties with fallback defaults.
+ * @alias module:@lumjs/core.opt
+ * @see module:@lumjs/core/opt
  */
 const opt = require('./opt');
 
 /**
  * Meta functions related to JS modules.
+ * @alias module:@lumjs/core.modules
+ * @see module:@lumjs/core/modules
  */
 const modules = require('./modules');
 
-// A few modules that we're going to expand into the main exports. 
+// ObjectID stuff is imported directly without registering a sub-module.
 const {randomNumber, InternalObjectId} = require('./objectid');
+
+/**
+ * Get a simplistic debugging stacktrace.
+ * @name module:@lumjs/core.stacktrace
+ * @function
+ * @see module:@lumjs/core/meta.stacktrace
+ */
+
+/**
+ * A simple base class for making *abstract* classes.
+ * @name module:@lumjs/core.AbstractClass
+ * @see module:@lumjs/core/meta.AbstractClass
+ */
+
+/**
+ * A *factory* for special types of JS `function` constructors.
+ * @name module:@lumjs/core.Functions
+ * @see module:@lumjs/core/meta.Functions
+ */
+
+/**
+ * Throw an `Error` saying that a feature is not yet implemented.
+ * @name module:@lumjs/core.NYI
+ * @function
+ * @see module:@lumjs/core/meta.NYI
+ */
+
+// These are exported directly, but a meta sub-module also exists.
+// Unlike most sub-modules there is no `meta` property in the main library.
 const {stacktrace,AbstractClass,Functions,NYI} = require('./meta');
 
-// And finally some standalone functions.
+/**
+ * Create a magic *Enum* object.
+ * @alias module:@lumjs/core.Enum
+ * @function
+ * @see module:@lumjs/core/enum
+ */
 const Enum = require('./enum');
-const lazy = require('./lazy');
+
+/**
+ * Make an object support the *Observable* API.
+ * @alias module:@lumjs/core.observable
+ * @function
+ * @see module:@lumjs/core/observable
+ */
 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
+ * @function
+ * @see module:@lumjs/core/types.def
+ */
 const def = types.def;
 
 module.exports =

package/lib/lazy.js

@@ -2,7 +2,7 @@
 const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
 
 /**
- * @callback InitFunc 
+ * @callback module:@lumjs/core~InitFunc 
  * @param {string} name - The `name` parameter passed to `lazy()`
  * @this {object} - The `obj` parameter passed to `lazy()`
  */
@@ -15,9 +15,10 @@ const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
  * 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 {Object} obj - The object to add the property to.
  * @param {string} name - The name of the property to add.
- * @param {InitFunc} initfunc - The function to initialize the property.
+ * @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,
@@ -36,14 +37,15 @@ const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
  * 
  *   If this is anything else, assignment will do nothing at all.
  * 
- * @param {object} [desc={}] Descriptor rules for the property.
+ * @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.
+ * @return {Object} The object we defined the property on.
+ * @alias module:@lumjs/core.lazy
  */
 function lazy(obj, name, initfunc, onset, desc={})
 {

package/lib/meta.js

@@ -1,3 +1,8 @@
+/**
+ * Meta-programming helpers.
+ * @module @lumjs/core/meta
+ */
+
 /**
  * Get a stacktrace. Differs from browser to browser.
  *
@@ -9,6 +14,7 @@
  * @param {string} [msg] - A message for the Error object.
  *
  * @returns {string[]} An array of stack strings.
+ * @alias module:@lumjs/core/meta.stacktrace
  */
 function stacktrace(msg)
 {
@@ -19,6 +25,7 @@ exports.stacktrace = stacktrace;
 
 /**
  * Abstract classes for Javascript.
+ * @alias module:@lumjs/core/meta.AbstractClass
  */
 class AbstractClass
 {
@@ -45,6 +52,8 @@ exports.AbstractClass = AbstractClass;
 
 /**
  * Function prototypes for async, generator, and async generator functions.
+ * @namespace
+ * @alias module:@lumjs/core/meta.Functions
  */
 const Functions =
 {
@@ -75,6 +84,7 @@ exports.Functions = Functions;
  * @param {string} [prefix=''] A prefix for the error message.
  * 
  * @returns {void}
+ * @alias module:@lumjs/core/meta.NYI
  */
 function NYI(fatal=true, prefix='') 
 { 

package/lib/modules.js

@@ -1,4 +1,7 @@
-// Stuff specific to mostly Node.js, but browser-shims may wrap this.
+/**
+ * Module helpers.
+ * @module @lumjs/core/modules
+ */
 
 const path = require('path');
 const {S,isObj} = require('./types');
@@ -7,7 +10,28 @@ const replace = require('./strings').replaceItems;
 /**
  * Get the name of a module.
  *
- * TODO: document this.
+ * @param {(object|string)} module - Either a module object, or filename.
+ *   If it is an `object`, it should be a CommonJS `module` object.
+ *   If it is a `string`, it should be the module filename.
+ * @param {object} [opts] Options.
+ * 
+ * @param {boolean} [opts.useAuto=true] Enable automatic name cleaning.
+ *   If *basename* mode was **not** used, then once all other rules have been 
+ *   applied, strip any leading `.` and `/` characters, and the file extension.
+ * 
+ * @param {boolean} [opts.basename=false] Use `path.basename()`
+ *   This will strip all parent directories, and the file extension.
+ *   If no other rules are specified in the `opts`, then this will
+ *   be applied automatically as a fallback method. If it is set to
+ *   `true` explicitly, then it will be applied *before* any other options.
+ * 
+ * @param {object} [opts.replace] Call {@link module:@lumjs/core/strings.replaceItems}
+ *   This uses the default `useAll` values based on the `object` format.
+ * @param {object} [opts.replaceOne] `replace` but `useAll` set to `false`.
+ * @param {object} [opts.replaceAll] `replace` but `useAll` set to `true`.
+ * @param {(string|string[])} [opts.strip] Sub-strings to remove entirely.
+ * @returns {string} The *name* of a module as per the options set.
+ * @alias module:@lumjs/core/modules.name
  */
 function name(module, opts={})
 {
@@ -29,7 +53,7 @@ function name(module, opts={})
   const ext = path.extname(filename);
 
   let useFallback = true;
-  let useAuto = !opts.noAuto;
+  let useAuto = opts.useAuto ?? true;
 
   if (opts.basename)
   { // We want to run the basename sequence first.