@lumjs/core 1.30.0 → 1.31.1

package/lib/obj/flip.js

@@ -59,6 +59,7 @@ function flip(obj, opts={})
  * @throws {ReferenceError} If `fatalDup` is `true`
  * and a duplicate value is found.
  * 
+ * @alias module:@lumjs/core/obj.flipKeyVal
  */
 function flipKeyVal(inObj, opts={})
 {
@@ -148,6 +149,7 @@ function flipKeyVal(inObj, opts={})
  * - If both `opts.valid.map` and `opts.valid.fatal` are `true`,
  *   and the validation tests against the `inMap` object fail.
  * 
+ * @alias module:@lumjs/core/obj.flipMap
  */
 function flipMap(inMap, opts={})
 {

package/lib/obj/index.js

@@ -13,6 +13,7 @@ const getProperty = require('./getproperty');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
+const cp = require('./cp');
 
 const 
 {
@@ -22,7 +23,7 @@ const
 
 module.exports =
 {
-  CLONE, clone, addClone, cloneIfLocked, lock, addLock,
+  cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,

package/lib/objectid.js

@@ -43,6 +43,13 @@ exports.randomNumber = randomNumber;
 
 const validBase = base => (typeof base === N && base > 1 && base < 37);
 
+/**
+ * A class for generating unique ids for objects.
+ * 
+ * TODO: document all the methods, etc.
+ * 
+ * @alias module:@lumjs/core.UniqueObjectIds
+ */
 class UniqueObjectIds
 {
   constructor(opts={})

package/lib/state.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const {S,isObj} = require('./types')
+const ctx = require('./context')
+const stateSym  = Symbol('@lumjs/core/state')
+const stateData = {[stateSym]: false}
+const stateKey  = 'LUM_JS_STATE'
+const stateOpts = {}
+
+module.exports =
+{
+  get(opts={})
+  {
+    if (opts.refresh || !stateData[stateSym])
+    {
+      let json;
+      if (ctx.isNode)
+      {
+        json = process.env[stateKey];
+      }
+      else if (ctx.isBrowser)
+      {
+        json = localStorage.getItem(stateKey);
+      }
+  
+      if (typeof json === S)
+      {
+        const revive = opts.jsonRevive ?? stateOpts.jsonRevive;
+        const storedData = JSON.parse(json, revive);
+        if (isObj(storedData))
+        {
+          Object.assign(stateData, storedData);
+          stateData[stateSym] = true;
+        }
+      }
+    }
+    return stateData;
+  },
+
+  save(opts={})
+  {
+    if (!stateData[stateSym]) return false;
+  
+    const replace = opts.jsonReplace ?? stateOpts.jsonReplace;
+    const json = JSON.stringify(stateData, replace);
+  
+    if (ctx.isBrowser)
+    {
+      localStorage.setItem(stateKey, json);
+    }
+    else if (ctx.isNode)
+    {
+      console.log("export ", stateKey, "=", json);
+    }
+  },
+
+  opts: stateOpts,
+  
+  [stateSym]: stateData,
+  $$: stateSym,
+}

package/lib/types/basics.js

@@ -3,21 +3,13 @@
 /**
  * Basic types sub-module.
  * 
- * Provides simple type tests, and a few one or two character constants
- * One or two character identifiers for the core JS type names.
+ * Provides a whole assortment of simple type test functions, 
+ * as well as all of the constants found in its `JS` property.
+ * Which means `basics.S === basics.JS.S`.
  * 
- * These are only the strings returned by the `typeof` operator.
- * See {@link module:@lumjs/core/types.TYPES} for a list
- * that includes special types and compound pseudo-types, etc.
- * 
- * @prop {string} O - object
- * @prop {string} F - function
- * @prop {string} S - string
- * @prop {string} B - boolean
- * @prop {string} N - number
- * @prop {string} U - undefined
- * @prop {string} SY - symbol
- * @prop {string} BI - bigint
+ * Unlike the `JS` object, this sub-module is NOT frozen/locked,
+ * although the JS constants are assigned as _non-configurable_ so
+ * they cannot be overwritten by different values.
  * 
  * @module @lumjs/core/types/basics
  */

package/lib/types/dt.js

@@ -49,11 +49,11 @@ const P = Object.freeze(
  * Similar magic properties may be added to bound instances of `def`;
  * I'll add further docs for that later. Look at the tests for examples.
  * 
- * @class
- * @alias module:@lumjs/core/types~DescriptorTemplate
- * 
  * The constructor function is also available via `def.DT`,
  * but using the built-in properties is easier.
+ * 
+ * @class
+ * @alias module:@lumjs/core/types~DescriptorTemplate
  */
 function DescriptorTemplate(opts={})
 {

package/lib/types/index.js

@@ -6,9 +6,6 @@
  * As `@lumjs/core` is the foundation for all my JS libraries,
  * this module is the foundation for `@lumjs/core`.
  * 
- * Re-exports everything from the {@link @lumjs/core/types/basics}
- * sub-module with the same names, and adds a whole lot more!
- * 
  * @module @lumjs/core/types
  */
 

package/lib/types/js.js

@@ -1,7 +1,26 @@
 "use strict";
 
-// A package-private collection of constants.
-// Exported as a part of `basics` and `index`.
+/**
+ * An absolutely minimal map of one or two letter string constants
+ * representing all of the fundamental JS types.
+ * 
+ * This object is *frozen* and cannot be modified in any way!
+ * 
+ * These are only the strings returned by the `typeof` operator.
+ * See {@link module:@lumjs/core/types.TYPES} for a much more complete
+ * list that includes special types and compound pseudo-types, etc.
+ * 
+ * @prop {string} O - object
+ * @prop {string} F - function
+ * @prop {string} S - string
+ * @prop {string} B - boolean
+ * @prop {string} N - number
+ * @prop {string} U - undefined
+ * @prop {string} SY - symbol
+ * @prop {string} BI - bigint
+ * 
+ * @memberof module:@lumjs/core/types/basics
+ */
 const JS =
 {
   O:  'object', 

package/lib/types/typelist.js

@@ -9,12 +9,14 @@ const
 /**
  * A map of **Types**, including *special* and *union* types.
  * 
- * Contains the same `O, F, S, B, N, U, SY, BI` properties as also
- * found in the top-level {@link module:@lumjs/core/types} module.
- * While most of the core JS types simply use `typeof` as their
+ * Contains the constants from {@link module:@lumjs/core/types/basics.JS},
+ * plus a whole bunch of _special types_ that require tests other than
+ * `typeof` to determine if a given value matches that type.
+ * 
+ * Also, while MOST of the core JS types simply use `typeof` as their
  * test, this maps the `O` (`object`) type to the `isObj` test.
  * 
- * Will also contain a few helper functions, and a map of tests
+ * It also contain a few helper functions, and a map of tests
  * that are used by `isType`, `isa`, `needType`, and `needs`.
  * Any one of these properties may be passed to those functions as
  * the desired *type* a desired value must be.

package/lum.build.js

@@ -0,0 +1,11 @@
+module.exports = function(rb)
+{
+  rb.readme
+    .add('docs/TODO.md')
+    .chdir('docs/changelogs')
+    .add('index.md')
+    .add('1.0-beta.md')
+    .add('1.x.md')
+    .add('2.x.md')
+    //.set('debug', true)
+}

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@lumjs/core",
-  "version": "1.30.0",
+  "version": "1.31.1",
   "main": "lib/index.js",
-  "exports":
+  "exports": 
   {
     ".": "./lib/index.js",
-
     "./arrays": "./lib/arrays/index.js",
     "./console": "./lib/console.js",
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
+    "./events": "./lib/events/index.js",
     "./flags": "./lib/flags.js",
     "./maps": "./lib/maps.js",
     "./meta": "./lib/meta.js",
     "./modules": "./lib/modules.js",
     "./obj": "./lib/obj/index.js",
+    "./obj/cp": "./lib/obj/cp.js",
     "./observable": "./lib/observable.js",
     "./opt": "./lib/opt/index.js",
     "./opt/args": "./lib/opt/args.js",
@@ -23,23 +24,28 @@
     "./types": "./lib/types/index.js",
     "./types/basics": "./lib/types/basics.js",
     "./types/def": "./lib/types/def.js",
-
     "./package.json": "./package.json"
   },
-  "license": "MIT",
-  "repository":
+  "dependencies": 
   {
-    "type": "git",
-    "url": "https://github.com/supernovus/lum.core.js.git"
+    "@lumjs/opts": "^1.0.0"
   },
-  "devDependencies":
+  "devDependencies": 
   {
-    "@lumjs/opts": "^1.0.0",
+    "@lumjs/build": "^1.1.0",
     "@lumjs/tests": "^2.0.0"
   },
-  "scripts":
+  "scripts": 
   {
     "test": "lumtest.js",
-    "build-docs": "jsdoc -c ./jsdoc.json"
-  }
+    "build-meta": "lum-build",
+    "build-jsdoc": "jsdoc -c ./jsdoc.js",
+    "build-docs": "npm run build-meta && npm run build-jsdoc"
+  },
+  "repository": 
+  {
+    "type": "git",
+    "url": "https://github.com/supernovus/lum.core.js.git"
+  },
+  "license": "MIT"
 }

package/TODO.md

@@ -1,76 +0,0 @@
-# TODO
-
-## v2.x
-
-I'm thinking it's getting close to time to do a big cleanup of the codebase,
-and refactor a few things that have gotten rather crufty. While there may be
-a few more releases in the `1.x` series, I think focusing on a clean break
-for the future would be a good idea. A few of the things I want to do:
-
-- Remove all deprecated code:
-  - `obj.{copyAll,duplicateOne,duplicateAll}`
-  - `types.instanceOf` and related options in `types.isa`
-  - `<meta>.AbstractClass`
-- Implement a new `obj.copy` API function/class
-  - Will completely replace `obj.{clone,copyProps,mergeNested}`
-  - Offer an extended version of the declarative API from `copyProps`
-  - Cut anything that seems superfluous or rarely used
-  - Add ability to copy `Symbol` properties
-- Replace `obj.syncNested` with `obj.sync` using the new `obj.copy` API
-- Move `opt.Opts` into its own separate package
-- Give `observable` some TLC
-
-I will likely update this list a bit before I get around to starting the
-new branch that will eventually become the `2.0.0` release.
-
-I also want to make a new version of the [@lumjs/compat] package that
-will be more helpful for major updates in the future, so it will have
-a corresponding `v2.x` release at the same time as this package.
-
-## Tests
-
-Write proper tests using [@lumjs/tests] library.
-This list of files is out of date and needs updating.
-
-  - [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`
-  - [ ] `obj/copyall`
-  - [ ] `obj/copyprops`
-  - [ ] `obj/clone`
-  - [ ] `obj/lock`
-  - [ ] `obj/merge`
-  - [ ] `obj/ns`
-  - [ ] `obj/index`
-  - [ ] `opt`
-  - [ ] `objectid`
-  - [ ] `meta`
-  - [ ] `enum`
-  - [ ] `lazy`
-  - [ ] `observable`
-  - [ ] `index`
-
-Would be nice to have the tests finished for the planned `2.x` release.
-
-## Documentation
-
-Go through all the DocBlocks and ensure the documentation is up-to-date and
-good enough to actually be useful.
-
-This would also be nice to have finished for the planned `2.x` release.
-
----
-
-[@lumjs/tests]: https://github.com/supernovus/lum.tests.js 
-[@lumjs/compat]: https://github.com/supernovus/lum.compat.js
-

package/jsdoc.json

@@ -1,33 +0,0 @@
-{
-  "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"
-  }
-}