MicroCODE's 'mcode-data' package

A public NPM Package of our internal data processing tools for Frontend and Backend JavaScript NodeJS projects.

This is an extremely 'light weight' package with _zero dependencies_.

Identical data and math handling on both...

- Frontend - in the Browser UI
- Backend - in the Server MVC

Description

This is our own internal data processing (data) code. It is used to gain more control over JavaScript data types and type coercion. Building large, extensible applications it is inevitable that you will have to carefully control data type coercion and handle type checking in a very common/consistent manner. Both of these can be defined as 'data handling', and this is our library for that in all our apps.

``
> node examples
`

Dependencies

- Production

1. None

- Development

1. Node.JS - standard runtime environment
2. JSDocs - our preferred JavaScript documentation system
3. Jest.JS - our preferred JavaScript testing framework

Development

When building a large application its important that the entire team agreed to common data handling practices.

$3

- Get to a terminal session in the local repo folder of your project.
- Use 'npm install' to load the package. It can be used 'stand-alone'...

`
npm install mcode-data
`

$3

This package includes a simple demo module: examples.js.
Running it directly will show you a set of examples for using all the data library functions.

- From your project directory after installation...

`
node .\node_modules\mcode-data\examples
`

...this will deomnstrate thru console logging various uses of the mcode-data functions.

- To test with JEST:
- From the mcode-data package directory...

`
npm install --save-dev jest
npm test
`

Included Functions

These are the functions we want at the ready in any module for development and debug.

| Function | Description | Usage |
| -------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| _Properties_ | | |
| property | Creates a property .set, .get, .validate, and .onchange. | mcode.property(options) |
| contextProperty | Defines a getter/setter proxy to sync instance to context. | mcode.contextProperty(instance, property, contextPath) |
| getProperty | Safely resolves a nested property using an array of keys. | mcode.getProperty(source, pathArray) |
| setProperty | Assigns a nested property on the target object. | mcode.setProperty(target, pathArray, value) |
| _Universal Export_ | | |
| classExport | Exports a class to the global or specified namespace. | mcode.classExport('Namespace', 'ClassName', factory) |
| _Type Checking_ | | |
| isString | Checks the type of an Object for String. | mcode.isString('stringToTest') |
| isObject | Checks the type of an Object for Object. | mcode.isObject(objectName) |
| isArray | Checks the type of an Object for Array. | mcode.isArray(arrayName) |
| isFunction | Checks the type of an Object for Function. | mcode.isFunction(objectName) |
| isNumber | Checks the type of an Object for Number. | mcode.isNumber(102022 or numberName) |
| ifNumber | Checks the type of an Object for Number, returns default. | mcode.ifNumber(102022 or numberName, defaultValue) |
| isNaN | Checks the type of an Object for NaN. | mcode.isNaN(numberName) |
| isJson | Checks the type of an Object for JSON. | mcode.isJson('{'JSON text'}' or objectName) |
| isHtml | Checks the type of an Object for HTML. | mcode.isHtml('<'HTML text'>' or objectName) |
| isDate | Checks the type of an Object for DATE. | mcode.isDate(timestamp) |
| isTimeStamp | Checks the type of an Object for TIME STAMP. | mcode.isTimeStamp(timestamp) |
| default | Returns a default value if an 'item' is 'blank'. | mcode.default(value, default) |
| _Utilities_ | | |
| sleep | Pauses execution for a specified duration in ms. | await mcode.sleep(500); |
| generateRandomId | Generates a random alpha-numeric ID of specified length. | mcode.generateRandomId('myobject') |
| encodeJson | Encodes a JSON object into a Base64 string. | mcode.encodeJson(jsonObject) |
| encodeAttr | Encodes a string for safe inclusion in HTML attributes. | mcode.encodeAttr('stringToEncode') |
| _Type Conversions_ | | |
| octify | Converts a string into octal bytes for log. | mcode.octify(stringToExamine) |
| hexify | Converts a string into hexadecimal bytes for log. | mcode.hexify(stringToExamine) |
| extractId | Extracts the first alpha-numeric ID Field from a string. | mcode.extractId("EP\_GPT13TZ1\_20231115_0800.L5K") |
| fromSnakeCase | Creates a 'Title Case String' from a 'snake-case-string'. | mcode.fromSnakeCase("snake-case-string") |
| toSnakeCase | Creates a 'snake-case-string' from a 'Title Case String'. | mcode.toSnakeCase("Title Case String") |
| _HTTP Support_ | | |
| HTTP_CODES | A STATIC list of common HTTP status codes and messages. | mcode.HTTP_CODES |
| isDomAvailable | Checks if the DOM APIs are available in the current environment. | mcode.isDomAvailable() |
| httpStatus | Converts a http status code into a message. | mcode.httpStatus(code) |
| httpSeverity | Converts a http status code into a log severity. | mcode.httpSeverity(code) |
| _UUID Support_ | | |
| uuidDecode | Decodes a UUID string into a JSON object. | mcode.uuidDecode('LLLLLLLL-MMMM-vHHH-VSSS-CNNNNNNNNNNN') |

$3

We believe in explicit code documentation, for other users, and for our 'future selves'.

JSDocs is a standardized system for documenting functions and data structures that produces three (3) primary outputs:

1. Inline documentation for the coder.
2. Intellisense popup documentation for the coder for every function.
3. External 'reference manual' documentation for your entire code base, if used consistently.

- This entire project--like all our projects--is documented with JSDocs.

- To install JSDocs use, get to a terminal session in the project folder...

`
npm install --save-dev jsdoc
`

- Configure JSDoc processing in...

`
jsdoc.json
`

- To regenerate the JSDocs from all source code, use the following command (from the project root directory)...

`
jsdoc -c .jsdoc.json
``

...then open ./docs/index.html

Help

Contact Timothy McGuire, support@mcode.com.

Terminology

| Word or Acronym | Description/Definition |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| NPM | Node Package Manager, actually “Node PM”, “Node pkgmakeinst” a system to deploy, install, and maintain NodeJS Apps. (PM was a BASH utility). |
| NVM | Node Version Manager, a tool that supports changing NodeJS versions. |
| MERN | MongoDB, Express, React, Node JS. |
| MongoDB | A ‘NoSQL’ database designed for Cloud applications, also referred to as a ‘Document Store’. |
| Express | Express is _not_ a database but rather an ‘extensible routing language’ for communication between a Client and a Server. |
| React | A Web UI development system, a JavaScript library developed by Facebook and made public—and Open Source—since 2013. |
| Node JS | A development stack that executes from a local file store—on a local Server—instead of from a network of servers. |
| JSDocs | A toolset to automatically generate API-style documentation from source code tagging. |

Authors

Contributor's names and contact info...

- Timothy McGuire @TimothyMcGuire - Founder, President-CEO of MicroCODE, Inc. a software and controls engineering company in Detroit, Michigan USA.

Version History

- v0.6.4
- Added 'encodeAttr()' to encode a string for safe inclusion in HTML attributes.
- Added 'isDomAvailable()' to check if the DOM APIs are available in the current environment.
- Added contextProperty() to define a getter/setter proxy that syncs instance properties to context paths.
- Added getProperty() to safely resolve a nested property using an array of keys.
- Added setProperty() to assign a nested property on the target object, creating scopes as needed.
- Added pre-generated JSDocs documentation in ./docs folder.
- v0.6.3
- Added 'classExport()' to return the created class constructor to support SSR and ESM module loading,
especially in HTMX applications.
- Added several new utilities: 'ifNumber()', 'encodeJson()', 'classExport()', 'generateRandomId()', 'sleep()'.
- v0.6.2
- Added 'macid' as named key for pulled UUIDv1 Node Address.
- Added httpSeverity() to return the severity of a HTTP status code as a string compatible with mcode-log.
- Added less common HTTP status codes to the list of known codes in HTTP_CODES.
- v0.6.1
- Added 'property(options)' to create a property with get, set methods, validator, and on change events.
- v0.6.0
- Added more standardized JSDoc module headers for inclusion in end-product documentation.
- v0.5.10
- Added 'default(anyItem, defaultItem)' function. It returns the defaultItem if anyItem is 'blank',
meaning null, undefined, or an 'empty' copy of the type.
- v0.5.9
- Minor optimizations.
- v0.5.8
- Updated 'httpStatus()' to use a STATIC copy of HTTP codes list for speed.
- Updated 'uuidDecode()' to use all STATIC text lists for speed.
- v0.5.7
- Corrected cross-spawn v7.0.0 - 7.0.4; Severity: high; Regular Expression Denial of Service.
- v0.5.6
- Updated 'uuidDecode()' to return the NIL UUID for a missing UUID parameter.
- v0.5.5
- Minor reformatting of the 'httpStatus()' message to [BRACKET] the subsystem producing the message.
- v0.5.4
- Corrected 'uuidDecode()' removed cnsole.log debug statement.
- v0.5.3
- Corrected 'uuidDecode()' handling of timestamps in UUIDv6 and UUIDv7.
- v0.5.2
- Added 'uuidDecode()' to display an immediate decoding of a UUID thru a JSON Object.
- v0.5.1
- Added 'httpStatus()' for use in mcode.resx() - see mcode-log package.
- v0.5.0
- All 'mcode-\*' packages updated with 'ready()' only implemented in 'mcode-log'.
- v0.4.3
- Corrected 'isJson()' to required the _1st_ character be a '{', not any character.
- v0.4.2
- Added 'fromSnakeCase()' and 'toSnakeCase()'.
- v0.4.1
- Removed accidental dependency upon mcode-log.
- v0.4.0
- Synchronized mcode-data, mcode-log, mcode-list, mcode-package.
- v0.3.9
- Reorganization, all 'is' functions first.
- v0.3.8
- Initial version, moved all data handling functions into new mcode-data package from mcode-log.
- v0.0.0
- Initial movement of our data handling functions from mcode-log to mcode-data.

Future Development

- v0.1.\*
- Any additional core code we will develop for general list processing work.
- Complex function execution with passed arguments or passed functions.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

MicroCODE Mantra

MicroCODE, Inc. was founded in 1987 as a controls engineering and software development company.

We specialize in manufacturing and quality control applications that must run 24x7x365 for years at a time.

Our slogan, distilled from over three decades of developing, testing, installing, and supporting 24x7x365
manufacturing applications, is..