@lumjs/core 1.0.0-beta.2 → 1.0.0

package/README.md

@@ -6,9 +6,18 @@ and work in CommonJS/Node.js and modern browsers without any modifications.
 
 Used by all the rest of my *Lum.js* libraries.
 
-## Exports
+## Documentation
 
-TODO: a brief summary of the exports.
+### [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](./docs/changelogs/1.x.md)
+### [TODO](TODO.md)
+### [Homepage](https://supernovus.github.io/)
 
 ## Official URLs
 

package/TODO.md

@@ -1,24 +1,31 @@
 # TODO
 
 - Proper tests using new [@lumjs/tests](https://github.com/supernovus/lum.tests.js) library.
-  - [ ] `index`
-  - [x] `types`
+  - [x] `types/js`
+  - [x] `types/basics` 
+  - [x] `types/root`
+  - [x] `types/isa`
+  - [x] `types/needs`
+  - [x] `types/def`
+  - [x] `types/typelist`
+  - [ ] `types/stringify`
+  - [x] `types/index`
+  - [x] `arrays`
   - [ ] `context`
   - [ ] `strings`
   - [ ] `flags`
-  - [ ] `descriptors`
   - [ ] `obj/copyall`
   - [ ] `obj/copyprops`
   - [ ] `obj/clone`
   - [ ] `obj/lock`
   - [ ] `obj/merge`
   - [ ] `obj/ns`
+  - [ ] `obj/index`
   - [ ] `opt`
   - [ ] `objectid`
   - [ ] `meta`
   - [ ] `enum`
-  - [ ] `prop`
   - [ ] `lazy`
   - [ ] `observable`
-- Anything that has a TODO notice in the code.
+  - [ ] `index`
 

package/docs/changelogs/1.0-beta.md

@@ -0,0 +1,99 @@
+# 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).
+
+## 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
+- Two new clone modes:
+  - `CLONE.DEEP` : A recursive clone of enumerable properties.
+  - `CLONE.ENTIRE` : A recursive clone of all properties.
+- Added `types.isa()` which wraps `isType()` and `isInstance()` along with some added magic that makes it a generic *smart match* function.
+- Added `types.needs()` which does for `isa()` what `needOb()` and `needType()` do for `isObj()` and `isType()` respectively.
+- A `jsdoc.json` based on the one from the old [Lum.js](https://github.com/supernovus/lum.js) codebase.
+- A temporary `test` script to the `package.json` which uses the `prove` utility from Perl 5.
+### Removed
+- Removed `descriptors` and `prop()` modules.
+  - They'll be in a new `@lumjs/compat` library for legacy compatibility code.
+### Changed
+- Updated this *changelog* which I forgot to do last time.
+- Fixed some formatting in the changelog.
+- Split `types` into separated files.
+- Moved/renamed a few functions:
+  - `types.containsAny()` → `arrays.containsAny()`
+  - `types.containsAll()` → `arrays.containsAll()`
+  - `types.removeFromArray()` → `arrays.removeItems()`
+  - `types.NYI()` → `meta.NYI()`
+- Updated tests to reflect the moved/renamed functions.
+- Enhanced `def()` function as it has fully replaced `prop()` now.
+  - Has a new `opts` parameter which can be used for a few different options.
+  - Allows assigning a *getter* and *setter* without using a descriptor.
+- Updated `lazy()` to be an extension of `def()` instead of `prop()`.
+- 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.
+
+## [1.0.0-beta.3] - 2022-07-11
+### Added
+- `core.context.hasRequire`: A boolean value indicating `require()`
+- `core.context.isNode`: A boolean value guessing the environment is node.js
+### Changed
+- `core.context.CJS`: Made slightly tighter in definition.
+- `core.modules.name()`: Made it more flexible.
+- `core.obj`: Changed namespace exports.
+### Fixed
+- `core.modules.name()`: Actually return the value!
+
+## [1.0.0-beta.2] - 2022-07-08
+### Changed
+- Renamed `src` to `lib` as we're not compiling/transpiling this code.
+- Moved `index.js` into `lib` with the rest of the module files.
+- Added `modules.js` with a method for generating a name/id for a module.
+- Added `isSearch()`,`isReplacement()`, and `replaceItems()` to `strings.js`.
+
+## [1.0.0-beta.1] - 2022-07-07
+### Added
+- Initial release.
+- Pulled a bunch of the core libraries from the old Lum.js project.
+- Refactored and reorganized the libraries a lot.
+
+[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
+[1.0.0-beta.1]: https://github.com/supernovus/lum.core.js/releases/tag/v1.0.0-beta.1
+

package/docs/changelogs/1.x.md

@@ -0,0 +1,17 @@
+# 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.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/jsdoc.json

@@ -0,0 +1,33 @@
+{
+  "tags": 
+  {
+    "allowUnknownTags": true
+  },
+  "source":
+  {
+    "include": ["./lib"]
+  },
+  "opts": 
+  {
+    "destination": "./docs/api",
+    "recurse": true
+  },
+  "plugins": 
+  [
+    "plugins/markdown"
+  ],
+  "templates": 
+  {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": 
+    {
+      "outputSourceFiles": true
+    },
+    "path": "ink-docstrap",
+    "theme": "cerulean",
+    "navType": "vertical",
+    "linenums": true,
+    "dateFormat": "YYYY-MM-DD, hh:mm:ss"
+  }
+}

package/lib/arrays.js

@@ -0,0 +1,78 @@
+/**
+ * Array helper functions.
+ * @module 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)
+ {
+   for (const item of items)
+   {
+     if (array.includes(item))
+     { // Item found.
+       return true;
+     }
+   }
+ 
+   // No items found.
+   return false;
+ }
+ 
+ exports.containsAny = containsAny;
+
+ /**
+  * See if an array contains *all* of the specified items.
+  * @param {Array} array
+  * @param  {...any} items 
+  * @returns {boolean}
+  * @alias module:@lumjs/core/arrays.containsAll
+  */
+ function containsAll(array, ...items)
+ {
+   for (const item of items)
+   {
+     if (!array.includes(item))
+     { // An item was missing.
+       return false;
+     }
+   }
+   
+   // All items found.
+   return true;
+ }
+
+ exports.containsAll = containsAll;
+ 
+/**
+ * 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;
+  for (const item of items)
+  {
+    const index = array.indexOf(item);
+    if (index !== -1)
+    {
+      array.splice(index, 1);
+      removed++;
+    }
+  }
+  return removed;
+}
+
+exports.removeItems = removeItems;

package/lib/context.js

@@ -1,24 +1,39 @@
 
-const {root,B,F,U,O,isObj,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;
 const cd = def(ctx, true);
 
 cd('AMD', typeof define === F && define.amd)
+  ('hasRequire', typeof require === F)
   ('hasExports', typeof exports !== U)
   ('hasModule', typeof module === O && module !== null)
-  ('CJS', ctx.hasModule && isObj(module.exports))
+  ('CJS', ctx.hasRequire && ctx.hasModule && isComplex(module.exports))
+  ('isNode', ctx.CJS && ctx.hasExports)
   ('isWindow', !ctx.CJS && rootHas('window'))
   ('isWorker', !ctx.CJS && rootHas('WorkerGlobalScope'))
   ('isServiceWorker', !ctx.CJS && rootHas('ServiceWorkerGlobalScope'))
@@ -26,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];
@@ -42,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 {S,def,notNil,isObj} = require('./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,7 +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);
+
+/**
+ * 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,69 +1,131 @@
-// 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.
- * @namespace types
+ * @alias module:@lumjs/core.types
+ * @see module:@lumjs/core/types
  */
 const types = require('./types');
-const def = types.def;
+
+/**
+ * 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.
- * @namespace context
+ * @alias module:@lumjs/core.context
+ * @see module:@lumjs/core/context
  */
 const context = require('./context');
 
 /**
  * Functions for working with strings and locales.
- * @namespace strings
+ * @alias module:@lumjs/core.strings
+ * @see module:@lumjs/core/strings
  */
 const strings = require('./strings');
 
 /**
  * Functions for working with binary flags.
- * @namespace flags
+ * @alias module:@lumjs/core.flags
+ * @see module:@lumjs/core/flags
  */
 const flags = require('./flags');
 
-/**
- * Functions and Enums for working with Descriptors.
- * @namespace descriptors
- */
-const descriptors = require('./descriptors');
-// The *primary* export from descriptors is DESC.
-const DESC = descriptors.DESC;
-
 /**
  * Functions for manipulating objects.
- * @namespace obj
+ * @alis module:@lumjs/core.obj
+ * @see module:@lumjs/core/obj
  */
 const obj = require('./obj');
 
 /**
  * Functions for getting values and properties with fallback defaults.
- * @namespace opt
+ * @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');
-const {stacktrace,AbstractClass,Functions} = require('./meta');
 
-// And finally some standalone functions.
+/**
+ * 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');
+
+/**
+ * Create a magic *Enum* object.
+ * @alias module:@lumjs/core.Enum
+ * @function
+ * @see module:@lumjs/core/enum
+ */
 const Enum = require('./enum');
-const prop = require('./prop');
-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 =
 {
-  types, context, strings, flags, descriptors, obj, opt,
-  randomNumber, InternalObjectId, Enum, prop, lazy, observable,
-  stacktrace, AbstractClass, Functions, def, DESC, modules,
+  types, arrays, context, strings, flags, obj, opt, modules,
+  def, randomNumber, InternalObjectId, Enum, lazy, observable,
+  stacktrace, AbstractClass, Functions, NYI,
 }