Naturally Produced Modules

    coerce-input

    0.1.0 • Public • Published

    Coerce Input

    Coerces values into JavaScript object types where available

    Byte size of Coerce Open Issues Open Pull Requests Build Test Status Latest commits Coerce Demo



    Requirements

    NodeJS development dependencies may be installed via NPM...

    npm install

    Note NPM is only required if adding features and/or fixing bugs, ie. there are no NPM based dependencies for utilizing this repository within other projects.


    Quick Start

    NodeJS projects may use npm to install coerce-input as a dependency...

    npm install coerce-input

    ... or as a development dependency via --save-dev command-line flag...

    npm install --save-dev coerce-input

    ... Check NodeJS Examples for details on how to import this project within your own source code.


    For projects on GitHub Pages, this repository encourages the use of Git Submodules to track dependencies

    Bash Variables

    _module_name='coerce-input'
    _module_https_url="https://github.com/javascript-utilities/coerce-input.git"
    _module_base_dir='assets/js/modules'
    _module_path="${_module_base_dir}/${_module_name}"

    Bash Submodule Commands

    cd "<your-git-project-path>"
    
    git checkout gh-pages
    mkdir -vp "${_module_base_dir}"
    
    git submodule add\
     -b master --name "${_module_name}"\
     "${_module_https_url}" "${_module_path}"

    Your ReadMe File

    Suggested additions for your ReadMe.md file so everyone has a good time with submodules

    Clone with the following to avoid incomplete downloads
    
    
        git clone --recurse-submodules <url-for-your-project>
    
    
    Update/upgrade submodules via
    
    
        git submodule update --init --merge --recursive

    Commit and Push

    git add .gitmodules
    git add "${_module_path}"
    
    
    ## Add any changed files too
    
    
    git commit -F- <<'EOF'
    :heavy_plus_sign: Adds `javascript-utilities/coerce-input#1` submodule
    
    
    
    **Additions**
    
    
    - `.gitmodules`, tracks submodules AKA Git within Git _fanciness_
    
    - `README.md`, updates installation and updating guidance
    
    - `_modules_/coerce-input`, Coerces values into JavaScript object types where available
    EOF
    
    
    git push origin gh-pages

    🎉 Excellent 🎉 your project is now ready to begin unitizing code from this repository!


    Usage

    Examples on how to utilize this repository


    NodeJS Example

    example.js

    #/usr/bin/env node
    
    'use strict';
    
    const { Coerce_Input } = require('coerce-input');
    
    const coerced_value = Coerce_Input('[42, "spam"]')
    
    console.log({coerced_value});
    //> { coerced_value: [ 42, 'spam' ] }
    
    console.log(typeof coerced_value[0]);
    //> number

    Web Application Example

    Note, there are Coerce Demo hosted by GitHub pages, the source code of which is available within the gh-pages branch of this repository.

    index.html

    <!DOCTYPE html>
    <html lang="en" dir="ltr">
      <head>
        <meta charset="utf-8">
        <script type="text/javascript" src="assets/js/modules/coerce-input/coerce-input.js" differ></script>
        <script type="text/javascript" src="assets/js/index.js" differ></script>
        <title>Test Value Coercion</title>
      </head>
      <body>
        <input type="text" id="client__text--input" value="">
        <pre id="client__text--output"></pre>
      </body>
    </html>

    index.js

    const text_input__callback = (event) => {
      const client_input = event.target.value;
      const coerce_input_value = Coerce_Input(client_input);
      const client_text_output = document.getElementById('client__text--output');
      const output_list = [ `typeof -> ${typeof coerce_input_value}` ];
    
      // Build pretty formatted output
      switch (typeof coerce_input_value) {
        case "string": {
          if (coerce_input_value.length === 0) {
            output_list.push('<empty string>');
          } else {
            output_list.push(`"${coerce_input_value.replace(/"/g, '\"')}"`);
          }
          break;
        }
    
        case "object": {
          if (Array.isArray(coerce_input_value)) {
            output_list.push(`Array [ ${coerce_input_value} ]`);
          } else {
            if (Object.keys(coerce_input_value).length === 0) {
              output_list.push('Object {  }');
            } else {
              output_list.push('Object {');
              Object.entries(coerce_input_value).reduce((accumulator, [key, value], index, array) => {
                let entry = `  ${key}: ${value}`;
                if (index < array.length - 1) {
                  entry += ',';
                }
                accumulator.push(entry);
                return accumulator;
              }, output_list);
              output_list.push('}');
            }
          }
          break;
        }
    
        default:
          output_list.push(coerce_input_value);
      }
    
      console.log(coerce_input_value);
      client_text_output.innerText = output_list.join('\n');
    };
    
    
    window.addEventListener('load', () => {
      const client_text_input = document.getElementById('client__text--input');
      client_text_input.addEventListener('input', text_input__callback);
    });

    Notes

    Warning if upgrading from v0.0.1 to v0.1.0 (or greater) then beware that this repository, and source code files, have been renamed from coerce to coerce-input, and exported function has been renamed from Coerce to Coerce_Input

    This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

    Developer Notes

    • Install developer dependencies via npm install

    • Edits to {Type,Java}Script files should be directed to files within the ts/ sub directory

    • Changes can be transpiled via npm run ts-build

    • Tests can be preformed via npm run ci-test


    Contributing

    Options for contributing to coerce-input and javascript-utilities


    Forking

    Start making a [Fork][iterator_cascade_callbacks__fork_it] of this repository to an account that you have write permissions for.

    • Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...
    cd ~/git/hub/javascript-utilities/coerce-input
    
    git remote add fork git@github.com:<NAME>/coerce-input.git
    • Commit your changes and push to your fork, eg. to fix an issue...
    cd ~/git/hub/javascript-utilities/coerce-input
    
    
    git commit -F- <<'EOF'
    :bug: Fixes #42 Issue
    
    
    **Edits**
    
    
    - `<SCRIPT-NAME>` script, fixes some bug reported in issue
    EOF
    
    
    git push fork main

    Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

    • Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

    Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.


    Sponsor

    Thanks for even considering it!

    Via Liberapay you may sponsor__shields_io__liberapay on a repeating basis.

    Regardless of if you're able to financially support projects such as coerce-input that javascript-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.


    Attribution


    License

    Documentation on coercing values into JavaScript object types where available
    Copyright (C) 2020 S0AndS0
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published
    by the Free Software Foundation, version 3 of the License.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
    

    For further details review full length version of AGPL-3.0 License.

    Install

    npm i coerce-input

    DownloadsWeekly Downloads

    1

    Version

    0.1.0

    License

    AGPL-3.0

    Unpacked Size

    69.1 kB

    Total Files

    11

    Last publish

    Collaborators

    • s0ands0