@lumjs/core 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -6,9 +6,14 @@ 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.
+I am working on fleshing out the documentation in `jsdoc3` format.
+You can compile the unfinished version using `jsdoc -c ./jsdoc.json` 
+which will put the generated docs into the `./docs/api` folder.
+
+### [Changelog](CHANGELOG.md)
+### [TODO](TODO.md)
 
 ## Official URLs
 

package/TODO.md

@@ -1,24 +1,37 @@
 # TODO
 
+## 1.0.0 Release
+
 - 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`
+  - [ ] `types/isa`
+  - [ ] `types/needs`
+  - [ ] `types/def`
+  - [ ] `types/typelist`
+  - [ ] `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`
+- 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

@@ -0,0 +1,69 @@
+# 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-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.
+
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.0.0-beta.4...HEAD
+[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/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,66 @@
+/** 
+ * See if an array contains *any* of the specified items.
+ * @param {Array} array 
+ * @param  {...any} items 
+ * @returns {boolean}
+ */
+ 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}
+  */
+ 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.
+* @param {Array} array 
+* @param  {...any} items 
+* @returns {number} Number of items removed.
+*/
+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,5 +1,5 @@
 
-const {root,B,F,U,O,isObj,def} = require('./types');
+const {root,B,F,U,O,isObj,isComplex,def} = require('./types');
 
 /**
  * Context object.
@@ -16,9 +16,11 @@ 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'))

package/lib/enum.js

@@ -1,5 +1,5 @@
-
-const {S,def,notNil,isObj} = require('./types')
+const types = require('./types');
+const {S,def,notNil,isObj,needObj} = types;
 const {InternalObjectId} = require('./objectid');
 
 const ENUM_ID = new InternalObjectId({name: '$Enum'});
@@ -117,7 +117,10 @@ function Enum (spec, opts={})
 
 } // Enum
 
-// Add an 'is' method.
+// Add an is() method.
 def(Enum, 'is', ENUM_ID.isFunction());
 
+// And an isEnum() method to the `types` namespace.
+def(types, 'isEnum', Enum.is);
+
 module.exports = Enum;

package/lib/index.js

@@ -3,46 +3,36 @@
 
 /**
  * Constants and functions for basic type checking.
- * @namespace types
  */
 const types = require('./types');
-const def = types.def;
+
+/**
+ * Array utility functions.
+ */
+const arrays = require('./arrays');
 
 /**
  * Information about the JS context we're running in.
- * @namespace context
  */
 const context = require('./context');
 
 /**
  * Functions for working with strings and locales.
- * @namespace strings
  */
 const strings = require('./strings');
 
 /**
  * Functions for working with binary flags.
- * @namespace 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
  */
 const obj = require('./obj');
 
 /**
  * Functions for getting values and properties with fallback defaults.
- * @namespace opt
  */
 const opt = require('./opt');
 
@@ -53,17 +43,17 @@ const modules = require('./modules');
 
 // A few modules that we're going to expand into the main exports. 
 const {randomNumber, InternalObjectId} = require('./objectid');
-const {stacktrace,AbstractClass,Functions} = require('./meta');
+const {stacktrace,AbstractClass,Functions,NYI} = require('./meta');
 
 // And finally some standalone functions.
 const Enum = require('./enum');
-const prop = require('./prop');
 const lazy = require('./lazy');
 const observable = require('./observable');
+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,
 }

package/lib/lazy.js

@@ -1,24 +1,24 @@
 
-const {S,F,isComplex} = require('./types');
-const prop = require('./prop');
-const {DESC} = require('./descriptors');
+const {S,F,TYPES:{COMPLEX},needType,needObj,def} = require('./types');
+
+/**
+ * @callback 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 prop} method, and indeed an
- * alias called `prop.lazy()` is also available.
+ * 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 {function} initfunc - The function to initialize the property.
- * 
- *   This function will have `this` set to the `obj` parameter.
- *   It will also be passed `name` as the sole parameter.
- * 
- * @param {mixed} [onset] How to handle assignment.
+ * @param {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.
@@ -36,29 +36,25 @@ const {DESC} = require('./descriptors');
  * 
  *   If this is anything else, assignment will do nothing at all.
  * 
- * @param {object} [desc=DESC.CONF] The Descriptor 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.
  */
-function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
+function lazy(obj, name, initfunc, onset, desc={})
 {
-  if (!isComplex(obj))
-  {
-    throw new TypeError("obj parameter was not an object");
-  }
-  if (typeof name !== S)
-  {
-    throw new TypeError("name parameter was not a string");
-  }
-  if (typeof initfunc !== F)
-  {
-    throw new TypeError("initfunc parameter was not a function");
-  }
+  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;
-  let setter = null;
 
-  function getter()
+  desc.get = function()
   {
     if (value === undefined)
     {
@@ -69,23 +65,23 @@ function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
 
   if (onset === true)
   { // Allow direct assignment.
-    setter = function(newval)
+    desc.set = function(newval)
     {
       value = newval;
     }
   }
   else if (onset === false)
   { // Throw an error on assignment.
-    setter = function()
+    desc.set = function()
     {
       throw new ReferenceError("The "+name+" property is read-only");
     }
   }
   else if (typeof onset === F)
   { // A proxy method for assignment.
-    setter = function(newval)
+    desc.set = function(newval)
     {
-      const setval = onset.call(this, newval);
+      const setval = onset.call(this, newval, value);
       if (setval !== undefined)
       {
         value = setval;
@@ -93,10 +89,10 @@ function lazy(obj, name, initfunc, onset, desc=DESC.CONF)
     }
   }
 
-  prop(obj, name, getter, setter, desc);
+  def(obj, name, desc);
 }
 
 // Gotta be one of the greatest lines...
-prop(prop, 'lazy', lazy);
+def(def, 'lazy', lazy);
 
 module.exports = lazy;

package/lib/meta.js

@@ -1,7 +1,14 @@
-
-
 /**
  * Get a stacktrace. Differs from browser to browser.
+ *
+ * Uses the `stack` property of an `Error` object as the source.
+ * This is a super simplistic hack. For a more complete solution, try
+ * the `stacktrace-js` library, which will be used in the new `@lumjs/debug`
+ * library as a dependency.
+ *
+ * @param {string} [msg] - A message for the Error object.
+ *
+ * @returns {string[]} An array of stack strings.
  */
 function stacktrace(msg)
 {
@@ -59,3 +66,23 @@ const Functions =
 }
 
 exports.Functions = Functions;
+
+/**
+ * A placeholder function for when something is not implemented.
+ * 
+ * @param {boolean} [fatal=true] If `true` throw Error.
+ *   If `false` use `console.error()` instead.
+ * @param {string} [prefix=''] A prefix for the error message.
+ * 
+ * @returns {void}
+ */
+function NYI(fatal=true, prefix='') 
+{ 
+  const msg = prefix+"« NOT YET IMPLEMENTED »";
+  if (fatal)
+    throw new Error(msg);
+  else
+    console.error(msg);
+}
+
+exports.NYI = NYI;

package/lib/modules.js

@@ -1,7 +1,7 @@
 // Stuff specific to mostly Node.js, but browser-shims may wrap this.
 
 const path = require('path');
-const {S,needObj,needType,isObj} = require('./types');
+const {S,isObj} = require('./types');
 const replace = require('./strings').replaceItems;
 
 /**
@@ -11,10 +11,21 @@ const replace = require('./strings').replaceItems;
  */
 function name(module, opts={})
 {
-  needObj(module);
-  needType(S, module.filename);
+  let filename;
+
+  if (typeof module === S)
+  { // Going to assume a string is the filename.
+    filename = module;
+  }
+  else if (isObj(module) && typeof module.filename === S)
+  { // It's a CommonJS module context object.
+    filename = module.filename;
+  }
+  else
+  { // Sorry, we don't support that.
+    throw new TypeError("Unsupported module parameter");
+  }
 
-  let filename = module.filename;
   const ext = path.extname(filename);
 
   let useFallback = true;
@@ -72,6 +83,7 @@ function name(module, opts={})
       .replace(RegExp(ext+'$'), '');
   }
 
+  return filename;
 }
 
 exports.name = name;