si-funciona 2.3.3 → 2.3.4

package/dist/helpers/descriptors/samples/mappedDescriptorMap.js

@@ -1,284 +1,287 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.default = void 0
-/**
- * @type {module:objectDescriptors~descriptorMap}
- * @memberOf module:objectDescriptors
- */
-const mappedDescriptorMap = [{
-  index: 0,
-  details: [{
-    index: 0,
-    key: 'index',
-    type: ['number'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 1,
-    key: 'details',
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: true,
-    isInstance: false,
-    arrayReference: 1,
-    objectReference: null
-  }, {
-    index: 2,
-    key: 'length',
-    type: ['number'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 3,
-    key: 'keys',
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: true,
-    isInstance: false,
-    arrayReference: 3,
-    objectReference: null
-  }, {
-    index: 4,
-    key: 'references',
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 5,
-    key: 'isArray',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 6,
-    key: 'complete',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }],
-  length: 7,
-  keys: ['index', 'details', 'length', 'keys', 'references', 'isArray', 'complete'],
-  references: [1, 3],
-  isArray: false,
-  complete: true
-}, {
-  index: 1,
-  details: [{
-    index: 0,
-    key: 0,
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: true,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: 2
-  }],
-  length: 1,
-  keys: [0],
-  references: [0],
-  isArray: true,
-  complete: true
-}, {
-  index: 2,
-  details: [{
-    index: 0,
-    key: 'index',
-    type: ['number'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 1,
-    key: 'key',
-    type: ['string'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 2,
-    key: 'type',
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: true,
-    isInstance: false,
-    arrayReference: 3,
-    objectReference: null
-  }, {
-    index: 3,
-    key: 'value',
-    type: ['object'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: true,
-    isInstance: false,
-    arrayReference: 3,
-    objectReference: null
-  }, {
-    index: 4,
-    key: 'nullable',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 5,
-    key: 'optional',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 6,
-    key: 'circular',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 7,
-    key: 'isReference',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 8,
-    key: 'isInstance',
-    type: ['boolean'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 9,
-    key: 'arrayReference',
-    type: ['object'],
-    value: [],
-    nullable: true,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }, {
-    index: 10,
-    key: 'objectReference',
-    type: ['object'],
-    value: [],
-    nullable: true,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }],
-  length: 11,
-  keys: ['index', 'key', 'type', 'value', 'nullable', 'optional', 'circular', 'isReference', 'isInstance', 'arrayReference', 'objectReference'],
-  references: [2, 3],
-  isArray: false,
-  complete: true
-}, {
-  index: 3,
-  details: [{
-    index: 0,
-    key: 0,
-    type: ['string'],
-    value: [],
-    nullable: false,
-    optional: false,
-    circular: false,
-    isReference: false,
-    isInstance: false,
-    arrayReference: null,
-    objectReference: null
-  }],
-  length: 1,
-  keys: [0],
-  references: [],
-  isArray: true,
-  complete: true
-}]
-var _default = exports.default = mappedDescriptorMap
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.default = void 0
+/**
+ * A worked example descriptorMap, produced by describing a `descriptor` value itself (i.e. describing the shape of
+ * a descriptor) - useful as a realistic fixture showing what a multi-entry descriptorMap with actual references
+ * looks like, since `descriptorSample`/`descriptorMapSample` alone only demonstrate a trivial single-entry case.
+ * @type {module:objectDescriptors~descriptorMap}
+ * @memberOf module:objectDescriptors
+ */
+const mappedDescriptorMap = [{
+  index: 0,
+  details: [{
+    index: 0,
+    key: 'index',
+    type: ['number'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 1,
+    key: 'details',
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: true,
+    isInstance: false,
+    arrayReference: 1,
+    objectReference: null
+  }, {
+    index: 2,
+    key: 'length',
+    type: ['number'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 3,
+    key: 'keys',
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: true,
+    isInstance: false,
+    arrayReference: 3,
+    objectReference: null
+  }, {
+    index: 4,
+    key: 'references',
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 5,
+    key: 'isArray',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 6,
+    key: 'complete',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }],
+  length: 7,
+  keys: ['index', 'details', 'length', 'keys', 'references', 'isArray', 'complete'],
+  references: [1, 3],
+  isArray: false,
+  complete: true
+}, {
+  index: 1,
+  details: [{
+    index: 0,
+    key: 0,
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: true,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: 2
+  }],
+  length: 1,
+  keys: [0],
+  references: [0],
+  isArray: true,
+  complete: true
+}, {
+  index: 2,
+  details: [{
+    index: 0,
+    key: 'index',
+    type: ['number'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 1,
+    key: 'key',
+    type: ['string'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 2,
+    key: 'type',
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: true,
+    isInstance: false,
+    arrayReference: 3,
+    objectReference: null
+  }, {
+    index: 3,
+    key: 'value',
+    type: ['object'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: true,
+    isInstance: false,
+    arrayReference: 3,
+    objectReference: null
+  }, {
+    index: 4,
+    key: 'nullable',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 5,
+    key: 'optional',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 6,
+    key: 'circular',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 7,
+    key: 'isReference',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 8,
+    key: 'isInstance',
+    type: ['boolean'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 9,
+    key: 'arrayReference',
+    type: ['object'],
+    value: [],
+    nullable: true,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }, {
+    index: 10,
+    key: 'objectReference',
+    type: ['object'],
+    value: [],
+    nullable: true,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }],
+  length: 11,
+  keys: ['index', 'key', 'type', 'value', 'nullable', 'optional', 'circular', 'isReference', 'isInstance', 'arrayReference', 'objectReference'],
+  references: [2, 3],
+  isArray: false,
+  complete: true
+}, {
+  index: 3,
+  details: [{
+    index: 0,
+    key: 0,
+    type: ['string'],
+    value: [],
+    nullable: false,
+    optional: false,
+    circular: false,
+    isReference: false,
+    isInstance: false,
+    arrayReference: null,
+    objectReference: null
+  }],
+  length: 1,
+  keys: [0],
+  references: [],
+  isArray: true,
+  complete: true
+}]
+var _default = exports.default = mappedDescriptorMap

package/dist/helpers/descriptors.d.ts

@@ -1,29 +1,45 @@
-/**
- * Create a format to standardize every object into a specific template.
- * @file
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.0.0
- * @module objectDescriptors
- * @memberOf module:siFunciona
- */
-import 'core-js/stable';
-declare const _default: {
-    assignDescriptor: (originalMap: import("./descriptors/samples/descriptor").descriptor, ...descriptors: Array<import("./descriptors/samples/descriptor").descriptor>) => import("./descriptors/samples/descriptor").descriptor;
-    assignDescriptorDetail: (originalDetail: import("./descriptors/samples/descriptorDetail").descriptorDetail, ...details: Array<import("./descriptors/samples/descriptorDetail").descriptorDetail>) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
-    checkClearValues: (descriptor: import("./descriptors/samples/descriptor").descriptor, keepValues?: boolean) => import("./descriptors/samples/descriptor").descriptor;
-    checkDescriptorComplete: (descriptor: import("./descriptors/samples/descriptor").descriptor) => import("./descriptors/samples/descriptor").descriptor;
-    cloneDescriptor: (originalMap: import("./descriptors/samples/descriptor").descriptor) => import("./descriptors/samples/descriptor").descriptor;
-    cloneDescriptorDetail: (originalDetail: import("./descriptors/samples/descriptorDetail").descriptorDetail) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
-    compareDescriptor: (descriptor1: import("./descriptors/samples/descriptor").descriptor, descriptor2: import("./descriptors/samples/descriptor").descriptor) => boolean;
-    describeObject: (object: import("./descriptors/describeObject").describeableObject) => import("./descriptors/samples/descriptor").descriptor;
-    describeObjectMap: (object: import("./descriptors/describeObject").describeableObject, { mapLimit, depthLimit, keepValues }?: {
-        mapLimit?: number;
-        depthLimit?: number;
-        keepValues?: boolean;
-    }) => import("./descriptors/samples/descriptorMap").descriptorMap;
-    describeObjectDetail: (value: any, key?: number | string, index?: number) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
-    nextReference: (descriptor: import("./descriptors/samples/descriptor").descriptor, currentReference: number) => number | undefined;
-    sameDescriptor: (descriptor1: import("./descriptors/samples/descriptor").descriptor, descriptor2: import("./descriptors/samples/descriptor").descriptor) => boolean;
-};
-export default _default;
+/**
+ * A "descriptor" is a flat, serializable snapshot of an object or array's shape: for each property, its type(s),
+ * whether it's nullable, and - if the property's own value is itself an object/array - a reference to that nested
+ * value's own descriptor elsewhere in the same list, rather than nesting descriptors inside descriptors. This flat,
+ * reference-based structure is what lets these utilities walk deeply nested and even circular object graphs (an
+ * object that contains itself, directly or indirectly) without infinite recursion, since a value that's already
+ * been described is simply pointed to again instead of re-described.
+ *
+ * Start with {@link module:objectDescriptors.describeObjectMap}, which takes any real object or array and produces
+ * this flat list of descriptors for you - the other functions here (comparing, merging, cloning descriptors) are
+ * building blocks used internally, or useful once you already have descriptors to work with directly.
+ *
+ * The concrete use this module has earned its keep on: describing two objects and comparing the results tells
+ * you whether they're the same shape and values even when they're different references entirely (see
+ * {@link module:objectDescriptors.sameDescriptor}/{@link module:objectDescriptors.compareDescriptor}) - useful
+ * anywhere you need to check that two objects genuinely match without caring whether they're literally the same
+ * instance. A descriptor also doubles as a flat, structured summary of an object's shape, which can be handy for
+ * discussion or assessment purposes (e.g. describing what an object looks like without dumping the whole thing).
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 1.0.0
+ * @module objectDescriptors
+ * @memberOf module:siFunciona
+ */
+import 'core-js/stable';
+declare const _default: {
+    assignDescriptor: (originalMap: import("./descriptors/samples/descriptor").descriptor, ...descriptors: Array<import("./descriptors/samples/descriptor").descriptor>) => import("./descriptors/samples/descriptor").descriptor;
+    assignDescriptorDetail: (originalDetail: import("./descriptors/samples/descriptorDetail").descriptorDetail, ...details: Array<import("./descriptors/samples/descriptorDetail").descriptorDetail>) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
+    checkClearValues: (descriptor: import("./descriptors/samples/descriptor").descriptor, keepValues?: boolean) => import("./descriptors/samples/descriptor").descriptor;
+    checkDescriptorComplete: (descriptor: import("./descriptors/samples/descriptor").descriptor) => import("./descriptors/samples/descriptor").descriptor;
+    cloneDescriptor: (originalMap: import("./descriptors/samples/descriptor").descriptor) => import("./descriptors/samples/descriptor").descriptor;
+    cloneDescriptorDetail: (originalDetail: import("./descriptors/samples/descriptorDetail").descriptorDetail) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
+    compareDescriptor: (descriptor1: import("./descriptors/samples/descriptor").descriptor, descriptor2: import("./descriptors/samples/descriptor").descriptor) => boolean;
+    describeObject: (object: import("./descriptors/describeObject").describeableObject) => import("./descriptors/samples/descriptor").descriptor;
+    describeObjectMap: (object: import("./descriptors/describeObject").describeableObject, { mapLimit, depthLimit, keepValues }?: {
+        mapLimit?: number;
+        depthLimit?: number;
+        keepValues?: boolean;
+    }) => import("./descriptors/samples/descriptorMap").descriptorMap;
+    describeObjectDetail: (value: any, key?: number | string, index?: number) => import("./descriptors/samples/descriptorDetail").descriptorDetail;
+    nextReference: (descriptor: import("./descriptors/samples/descriptor").descriptor, currentReference: number) => number | undefined;
+    sameDescriptor: (descriptor1: import("./descriptors/samples/descriptor").descriptor, descriptor2: import("./descriptors/samples/descriptor").descriptor) => boolean;
+};
+export default _default;
 //# sourceMappingURL=descriptors.d.ts.map