itee-validators 5.5.0 → 5.6.0

package/.github/workflows/node.js.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Install dependencies
         run: npm ci
       - name: Release
-        run: npm run clean && npm run lint && npm run doc && npm run build-test && npm run test
+        run: npm run lint && npm run build && npm run build-test && npm run test
 
   publish:
     needs: build

package/.tasks/_utils.mjs

@@ -0,0 +1,66 @@
+import {
+    join,
+    dirname
+}                        from 'path'
+import { readFileSync }  from 'fs'
+import { fileURLToPath } from 'url'
+
+// We cannot use directly the import.meta.dirname or filename because all IDE usage do not produce them
+// We use
+function getDirname() {
+
+    let __dirname
+
+    if ( import.meta.dirname ) {
+        __dirname = import.meta.dirname
+    } else if ( import.meta.filename ) {
+        __dirname = dirname( import.meta.filename )
+    } else if ( import.meta.url ) {
+        const __filename = fileURLToPath( import.meta.url )
+        __dirname        = dirname( __filename )
+    } else {
+        throw new Error( 'Unable to retrieve module dirname.' )
+    }
+
+    // Todo: distinguish between dirname and packageRootFolder to avoid misusing
+    __dirname = join( __dirname, '..' )
+
+    return __dirname
+
+}
+
+const __dirname    = getDirname()
+const packagePath  = join( __dirname, 'package.json' )
+const packageData  = readFileSync( packagePath )
+const packageInfos = JSON.parse( packageData )
+
+class Indenter {
+
+    _          = ''
+    __         = ''
+    ___        = ''
+    ____       = ''
+    _____      = ''
+    ______     = ''
+    _______    = ''
+    ________   = ''
+    _________  = ''
+    __________ = ''
+
+    constructor( indentationChar = '\t', maxIndentationLevel = 10 ) {
+
+        let currentProperty = '_'
+        for ( let currentIndentationLevel = 1 ; currentIndentationLevel <= maxIndentationLevel ; currentIndentationLevel++ ) {
+            this[ currentProperty ] = indentationChar.repeat( currentIndentationLevel )
+            currentProperty += '_'
+        }
+
+    }
+
+}
+
+export {
+    packageInfos,
+    Indenter,
+    getDirname
+}

package/.tasks/builds/build.mjs

@@ -0,0 +1,65 @@
+import { join }           from 'path'
+import rollupConfigurator from '../../configs/rollup.conf.js'
+import parseArgs          from 'minimist'
+import { getDirname }     from '../_utils.mjs'
+import { packageInfos }   from '../_utils.mjs'
+import { rollup }         from 'rollup'
+import log                from 'fancy-log'
+
+function build( done ) {
+
+    const __dirname = getDirname()
+
+    const options = parseArgs( process.argv, {
+        string:  [ 'n', 'i', 'f', 'e' ],
+        boolean: [ 's', 't' ],
+        default: {
+            i: join( __dirname, 'sources', `${ packageInfos.name }.js` ),
+            o: join( __dirname, 'builds' ),
+            f: [ 'esm', 'cjs', 'iife' ],
+            e: [ 'dev', 'prod' ],
+            s: true,
+            t: true
+        },
+        alias:   {
+            i: 'input',
+            o: 'output',
+            f: 'formats',
+            e: 'envs',
+            s: 'sourcemap',
+            t: 'treeshake'
+        }
+    } )
+
+    const configs = rollupConfigurator( options )
+
+    nextBuild()
+
+    function nextBuild( error ) {
+        'use strict'
+
+        if ( error ) {
+
+            done( error )
+
+        } else if ( configs.length === 0 ) {
+
+            done()
+
+        } else {
+
+            const config = configs.pop()
+            log( `Building ${ config.output.file }` )
+
+            rollup( config )
+                .then( ( bundle ) => { return bundle.write( config.output ) } )
+                .then( () => { nextBuild() } )
+                .catch( nextBuild )
+
+        }
+
+    }
+
+}
+
+export { build }

package/.tasks/cleans/clean.mjs

@@ -0,0 +1,20 @@
+import { getGulpConfigForTask } from '../../configs/gulp.conf.mjs'
+import { deleteAsync }          from 'del'
+import log                      from 'fancy-log'
+import colors                   from 'ansi-colors'
+
+const red = colors.red
+
+function clean( done ) {
+
+    const filesToClean = getGulpConfigForTask( 'clean' )
+
+    for ( let fileIndex = 0, numberOfFiles = filesToClean.length ; fileIndex < numberOfFiles ; fileIndex++ ) {
+        log( red( `[${ fileIndex + 1 }/${ numberOfFiles }] Delete ${ filesToClean[ fileIndex ] }` ) )
+    }
+
+    return deleteAsync( filesToClean )
+
+}
+
+export { clean }

package/.tasks/docs/doc.mjs

@@ -0,0 +1,37 @@
+import log                      from 'fancy-log'
+import jsdocConfiguration       from '../../configs/jsdoc.conf.js'
+import { getGulpConfigForTask } from '../../configs/gulp.conf.mjs'
+import gulp                     from 'gulp'
+import jsdoc                    from 'gulp-jsdoc3'
+
+
+async function doc( done ) {
+
+    const config     = jsdocConfiguration
+    const filesToDoc = getGulpConfigForTask( 'doc' )
+
+    for ( let fileIndex = 0, numberOfFiles = filesToDoc.length ; fileIndex < numberOfFiles ; fileIndex++ ) {
+        log( `[${ fileIndex + 1 }/${ numberOfFiles }] Documenting ${ filesToDoc[ fileIndex ] }` )
+    }
+
+    // gulp
+    //     .src( filesToDoc, {
+    //         read:       false,
+    //         allowEmpty: true
+    //     } )
+    //     .pipe( jsdoc( config, done ) )
+    //     .on( 'error', done )
+
+    await new Promise( ( ( resolve, reject ) => {
+        gulp.src( filesToDoc, {
+            read:       false,
+            allowEmpty: true
+        } )
+            .pipe( jsdoc( config, resolve ) )
+            .on( 'error', reject )
+    } ) )
+    done()
+
+}
+
+export { doc }

package/.tasks/helps/help.mjs

@@ -0,0 +1,195 @@
+import childProcess from 'child_process'
+import log          from 'fancy-log'
+import colors       from 'ansi-colors'
+import {
+    packageInfos,
+    Indenter
+}                   from '../_utils.mjs'
+
+const {
+          red,
+          green,
+          blue,
+          cyan,
+          yellow,
+          magenta,
+          unstyle
+      } = colors
+
+function getPrettyPackageName() {
+
+    let packageName = ''
+
+    const nameSplits = packageInfos.name.split( '-' )
+    for ( const nameSplit of nameSplits ) {
+        packageName += nameSplit.charAt( 0 ).toUpperCase() + nameSplit.slice( 1 ) + ' '
+    }
+    packageName = packageName.slice( 0, -1 )
+
+    return packageName
+
+}
+
+function getPrettyPackageVersion() {
+
+    return 'v' + packageInfos.version
+
+}
+
+function getPrettyNodeVersion() {
+
+    let nodeVersion = 'vX.x.ₓ'
+
+    try {
+        nodeVersion = childProcess.execFileSync( 'node', [ '--version' ] )
+                                  .toString()
+                                  .replace( /(\r\n|\n|\r)/gm, '' )
+    } catch ( e ) {
+        log( red( e ) )
+
+        if ( e.message.includes( 'ENOENT' ) ) {
+            nodeVersion += yellow( ' Not seems to be accessible from the path environment.' )
+        }
+    }
+
+    return ' node: ' + nodeVersion
+
+}
+
+function getPrettyNpmVersion() {
+
+    let npmVersion = 'X.x.ₓ'
+
+    try {
+        npmVersion = childProcess.execFileSync( 'npm', [ '--version' ] )
+                                 .toString()
+                                 .replace( /(\r\n|\n|\r)/gm, '' )
+    } catch ( e ) {
+        log( red( e ) )
+
+        if ( e.message.includes( 'ENOENT' ) ) {
+            npmVersion += yellow( ' Not seems to be accessible from the path environment.' )
+        }
+    }
+
+    return ' npm:  v' + npmVersion
+
+}
+
+function alignTextCenter( text, width ) {
+
+    const unstyledText = unstyle( text.repeat( 1 ) )
+    const marginLength = ( width - unstyledText.length ) / 2
+
+    let leftMargin, rightMargin
+    if ( Number.isInteger( marginLength ) ) {
+        leftMargin  = marginLength
+        rightMargin = marginLength
+    } else {
+        const flooredMargin = Math.floor( marginLength )
+        leftMargin          = flooredMargin
+        rightMargin         = flooredMargin + 1
+    }
+
+    return ' '.repeat( leftMargin ) + text + ' '.repeat( rightMargin )
+
+}
+
+function alignTextLeft( text, width ) {
+
+    const unstyledText = unstyle( text.repeat( 1 ) )
+    let repeatTime     = width - unstyledText.length
+    repeatTime         = ( repeatTime > 0 ) ? repeatTime : 0
+
+    return text + ' '.repeat( repeatTime )
+
+}
+
+function alignTextRight( text, width ) {
+
+    const unstyledText = unstyle( text.repeat( 1 ) )
+    let repeatTime     = width - unstyledText.length
+    repeatTime         = ( repeatTime > 0 ) ? repeatTime : 0
+
+    return ' '.repeat( repeatTime ) + text
+
+}
+
+function help( done ) {
+
+    const bannerWidth          = 70
+    const prettyPackageName    = getPrettyPackageName()
+    const prettyPackageVersion = getPrettyPackageVersion()
+    const prettyNodeVersion    = getPrettyNodeVersion()
+    const prettyNpmVersion     = getPrettyNpmVersion()
+
+    const tableCharset = {
+        topLeftCorner:       '┏',
+        topRightCorner:      '┓',
+        bottomRightCorner:   '┛',
+        bottomLeftCorner:    '┗',
+        horizontalBorder:    '━',
+        horizontalSeparator: '─',
+        leftJoinSeparator:   '┠',
+        rightJoinSeparator:  '┨',
+        verticalBorder:      '┃',
+        verticalSeparator:   '',
+    }
+
+    const mainBorder     = tableCharset.horizontalBorder.repeat( bannerWidth )
+    const thinBorder     = tableCharset.horizontalSeparator.repeat( bannerWidth )
+    const tableTop       = `${ tableCharset.topLeftCorner }${ mainBorder }${ tableCharset.topRightCorner }`
+    const tableSeparator = `${ tableCharset.leftJoinSeparator }${ thinBorder }${ tableCharset.rightJoinSeparator }`
+    const tableBottom    = `${ tableCharset.bottomLeftCorner }${ mainBorder }${ tableCharset.bottomRightCorner }`
+    const tableLine      = ( innerText ) => `${ tableCharset.verticalBorder }${ innerText }${ tableCharset.verticalBorder }`
+
+    const I      = new Indenter( '  ', 5 )
+    const npmRun = blue( 'npm run' )
+
+    log( '' )
+    log( tableTop )
+    log( tableLine( alignTextCenter( 'HELP', bannerWidth ) ) )
+    log( tableLine( alignTextCenter( prettyPackageName, bannerWidth ) ) )
+    log( tableLine( alignTextCenter( prettyPackageVersion, bannerWidth ) ) )
+    log( tableSeparator )
+    log( tableLine( alignTextLeft( prettyNodeVersion, bannerWidth ) ) )
+    log( tableLine( alignTextLeft( prettyNpmVersion, bannerWidth ) ) )
+    log( tableBottom )
+    log( I._, 'Available commands are:' )
+    log( I.__, npmRun, cyan( 'help' ), '- Display this help.' )
+    log( I.__, npmRun, cyan( 'patch' ), '- Will apply some patch/replacements in dependencies.', red( '(Apply only once after run "npm install")' ) )
+    log( I.__, npmRun, cyan( 'clean' ), '- Will delete builds and temporary folders.' )
+    log( I.__, npmRun, cyan( 'lint' ), '- Will run the eslint in pedantic mode with auto fix when possible.' )
+    log( I.__, npmRun, cyan( 'doc' ), '- Will run jsdoc, and create documentation under `documentation` folder, using the docdash theme' )
+    log( I.__, npmRun, cyan( 'test' ), '- Will run the test framworks (unit and bench), and create reports under `documentation/report` folder, using the mochawesome theme' )
+    log( I.__, npmRun, cyan( 'unit' ), '- Will run the karma server for unit tests.' )
+    log( I.__, npmRun, cyan( 'bench' ), '- Will run the karma server for benchmarks.' )
+    log( I.__, npmRun, cyan( 'build' ), yellow( '--' ), green( '<options>' ), '- Will build the application for development and/or production environments.' )
+    log( I.___, yellow( 'Note: The two dash are only required if you provide options !' ) )
+    log( I.___, 'The available', green( '<options>' ), 'are:' )
+    log( I.____, green( '-i' ), 'or', green( '--input' ), '- The main file path to build', cyan( '[Default: "sources/main.js"]' ), '.' )
+    log( I.____, green( '-o' ), 'or', green( '--output' ), '- The folder where output the build', cyan( '[Default: "builds"]' ), '.' )
+    log(
+        I.____,
+        green( '-f:' ),
+        magenta( '<format>' ),
+        'or',
+        green( '--format:' ),
+        magenta( '<format>' ),
+        ' - to specify the output build type. Where format could be any of:', magenta( 'cjs, esm, iife, umd' ), '.'
+    )
+    log( I.____, green( '-e:' ), magenta( '<env>' ), 'or', green( '--env:' ), magenta( '<env>' ), ' - to specify the build environment. Where env could be any of:', magenta(
+        'dev' ), magenta( 'prod' ), cyan( '[Default: "dev"]' ), '.' )
+    log( I.____, green( '-s' ), 'or', green( '--sourcemap' ), ' - to build with related source map', cyan( '[Default: true]' ), '.' )
+    log( I.____, green( '-t' ), 'or', green( '--treeshake' ), ' - allow to perform treeshaking when building', cyan( '[Default: true]' ), '.' )
+    log( I.__, npmRun, cyan( 'release' ), '- Will run all the lint, test stuff, and if succeed will build the application.' )
+    log( '' )
+    log( I._, 'In case you have', blue( 'gulp' ), 'installed globally, you could use also:' )
+    log( I.__, blue( 'gulp' ), cyan( 'command' ), '- It will perform the command like using "npm run" but with less characters to type... Because you\'re a developer, right ?' )
+    log( '' )
+
+    done()
+
+}
+
+export { help }

package/.tasks/lints/lint.mjs

@@ -0,0 +1,33 @@
+import { getGulpConfigForTask } from '../../configs/gulp.conf.mjs'
+import gulp                     from 'gulp'
+import eslint                   from 'gulp-eslint'
+import log                      from 'fancy-log'
+
+function lint( done ) {
+
+    const filesToLint = getGulpConfigForTask( 'lint' )
+
+    for ( let fileIndex = 0, numberOfFiles = filesToLint.length ; fileIndex < numberOfFiles ; fileIndex++ ) {
+        log( `[${ fileIndex + 1 }/${ numberOfFiles }] Lint ${ filesToLint[ fileIndex ] }` )
+    }
+
+    return gulp.src( filesToLint, { base: './' } )
+               .pipe( eslint( {
+                   allowInlineConfig: true,
+                   globals:           [],
+                   fix:               true,
+                   quiet:             false,
+                   envs:              [],
+                   configFile:        './configs/eslint.conf.js',
+                   parserOptions:     {},
+                   plugins:           [],
+                   rules:             {},
+                   useEslintrc:       false
+               } ) )
+               .pipe( eslint.format( 'stylish' ) )
+               .pipe( gulp.dest( '.' ) )
+               .pipe( eslint.failAfterError() )
+
+}
+
+export { lint }

package/.tasks/patches/patch.mjs

@@ -0,0 +1,9 @@
+
+
+function patch( done ) {
+
+    done()
+
+}
+
+export { patch }

package/.tasks/tests/benchmarks/bundle-benchmarks.mjs

@@ -0,0 +1,33 @@
+import rollupBenchesConfigurator from '../../../configs/rollup.benchs.conf.js'
+import log                       from 'fancy-log'
+import { rollup }                from 'rollup'
+import colors                    from 'ansi-colors'
+
+const red = colors.red
+
+async function bundleBenchmarks( done ) {
+
+    const configs = rollupBenchesConfigurator()
+
+    for ( let config of configs ) {
+
+        log( `Building ${ config.output.file }` )
+
+        try {
+
+            const bundle = await rollup( config )
+            await bundle.write( config.output )
+
+        } catch ( error ) {
+
+            log( red( error ) )
+
+        }
+
+    }
+
+    done()
+
+}
+
+export { bundleBenchmarks }

package/.tasks/tests/benchmarks/compute-benchmarks.mjs

@@ -0,0 +1,215 @@
+import {
+    join,
+    normalize,
+    basename,
+    dirname,
+    extname,
+    relative
+}                               from 'path'
+import {
+    getDirname,
+    packageInfos
+}                               from '../../_utils.mjs'
+import glob                     from 'glob'
+import fs                       from 'fs'
+import log                      from 'fancy-log'
+import colors                   from 'ansi-colors'
+import { getGulpConfigForTask } from '../../../configs/gulp.conf.mjs'
+import childProcess             from 'child_process'
+
+const {
+          red,
+          green,
+          blue,
+          cyan,
+          yellow,
+          magenta
+      } = colors
+
+
+function computeBenchmarks( done ) {
+
+    const baseDir    = getDirname()
+    const sourcesDir = join( baseDir, 'sources' )
+    const testsDir   = join( baseDir, 'tests' )
+    const benchesDir = join( testsDir, 'benchmarks' )
+
+    fs.mkdirSync( benchesDir, { recursive: true } )
+
+    const filePathsToIgnore = getGulpConfigForTask( 'compute-benchmarks' )
+
+    const sourcesFiles = glob.sync( join( sourcesDir, '**' ) )
+                             .map( filePath => normalize( filePath ) )
+                             .filter( filePath => {
+                                 const fileName         = basename( filePath )
+                                 const isJsFile         = fileName.endsWith( '.js' )
+                                 const isNotPrivateFile = !fileName.startsWith( '_' )
+                                 const isNotIgnoredFile = !filePathsToIgnore.includes( fileName )
+                                 return isJsFile && isNotPrivateFile && isNotIgnoredFile
+                             } )
+
+    const benchRootImports = []
+    for ( let sourceFile of sourcesFiles ) {
+
+        const specificFilePath = sourceFile.replace( sourcesDir, '' )
+        const specificDir      = dirname( specificFilePath )
+
+        const fileName      = basename( sourceFile, extname( sourceFile ) )
+        const benchFileName = `${ fileName }.bench.js`
+        const benchDirPath  = join( benchesDir, specificDir )
+        const benchFilePath = join( benchDirPath, benchFileName )
+
+        const nsName         = `${ fileName }Namespace`
+        const importDirPath  = relative( benchDirPath, sourcesDir )
+        const importFilePath = join( importDirPath, specificFilePath ).replace( /\\/g, '/' )
+
+        try {
+
+            const jsdocPath   = join( baseDir, '/node_modules/jsdoc/jsdoc.js' )
+            const jsdocOutput = childProcess.execFileSync( 'node', [ jsdocPath, '-X', sourceFile ] ).toString()
+
+            const classNames    = []
+            const usedLongnames = []
+            const jsonData      = JSON.parse( jsdocOutput ).filter( data => {
+
+                const longName = data.longname
+
+                const kind = data.kind
+                if ( kind !== 'function' ) {
+                    if ( kind === 'class' && !classNames.includes( longName ) ) {
+                        classNames.push( longName )
+                    }
+                    return false
+                }
+
+                // We don't care that data bloc have comment they are unused to generate benchmarks
+                // const undocumented = data.undocumented
+                // if ( undocumented ) {
+                //     return false
+                // }
+
+                const scope = data.scope
+                if ( ![ 'global', 'static' ].includes( scope ) ) {
+                    return false
+                }
+
+                if ( longName.includes( ' ' ) || longName.includes( '~' ) || usedLongnames.includes( longName ) ) {
+                    return false
+                }
+
+                for ( let className of classNames ) {
+                    if ( longName.includes( className ) ) {
+                        return false
+                    }
+                }
+
+                usedLongnames.push( longName )
+
+                return true
+
+            } )
+
+            if ( jsonData.length === 0 ) {
+                log( yellow( `No usable exports found in [${ sourceFile }]. Ignore it !` ) )
+                continue
+            }
+
+            // Compute benchmark suites by grouping logically function by name[_x]
+            const suiteGroups = {}
+            for ( let docData of jsonData ) {
+
+                try {
+
+                    const functionName = docData.name
+                    const nameSplits   = functionName.split( '_' )
+                    const rootName     = nameSplits[ 0 ]
+
+                    if ( !( rootName in suiteGroups ) ) {
+                        suiteGroups[ rootName ] = []
+                    }
+
+                    suiteGroups[ rootName ].push( functionName )
+
+                } catch ( error ) {
+
+                    log( red( error.message ) )
+
+                }
+
+            }
+
+            // Generate suites
+            let benchSuites       = ''
+            const suitesToExports = []
+            for ( let suiteGroupName in suiteGroups ) {
+                suitesToExports.push( `${ suiteGroupName }Suite` )
+                benchSuites += `const ${ suiteGroupName }Suite = Benchmark.Suite( '${ nsName }.${ suiteGroupName }', Testing.createSuiteOptions() )` + '\n'
+
+                for ( let suiteGroupValue of suiteGroups[ suiteGroupName ] ) {
+                    benchSuites += `                                     .add( '${ suiteGroupValue }()', Testing.iterateOverDataMap( ${ nsName }.${ suiteGroupValue } ), Testing.createBenchmarkOptions() )` + '\n'
+                }
+
+                benchSuites += '\n'
+            }
+
+            const template = '' + '\n' +
+                `import Benchmark   from 'benchmark'` + '\n' +
+                `import { Testing }      from 'itee-utils'` + '\n' +
+                `import * as ${ nsName } from '${ importFilePath }'` + '\n' +
+                '\n' +
+                `${ benchSuites }` +
+                // '\n' +
+                `export { ${ suitesToExports } }` + '\n' +
+                '\n'
+
+            const importBenchFilePath = relative( benchesDir, benchFilePath ).replace( /\\/g, '/' )
+            benchRootImports.push( {
+                path:    importBenchFilePath,
+                exports: suitesToExports
+            } )
+
+            log( green( `Create ${ benchFilePath }` ) )
+            fs.mkdirSync( benchDirPath, { recursive: true } )
+            fs.writeFileSync( benchFilePath, template )
+
+        } catch ( error ) {
+
+            log( red( error.message ) )
+
+        }
+
+    }
+
+    let templateImports = ''
+    let suites          = []
+    for ( let i = 0 ; i < benchRootImports.length ; i++ ) {
+
+        const currentBench = benchRootImports[ i ]
+        const exports      = currentBench.exports
+        const imports      = exports.join( ', ' )
+        suites.push( ...exports )
+
+        templateImports += `import {${ imports }} from './${ currentBench.path }'` + '\n'
+
+    }
+
+    const benchesTemplate = '' +
+        `${ templateImports }` + '\n' +
+        'const suites = [' + '\n' +
+        `${ suites.map( suite => `\t${ suite }` ).join( ',\n' ) }` + '\n' +
+        ']' + '\n' +
+        '\n' +
+        `for ( const suite of suites ) {` + '\n' +
+        `\tsuite.run()` + '\n' +
+        `}` + '\n'
+
+    const benchesFilePath = join( benchesDir, `${ packageInfos.name }.benchs.js` )
+
+    log( green( `Create ${ benchesFilePath }` ) )
+    fs.writeFileSync( benchesFilePath, benchesTemplate )
+
+    done()
+
+}
+
+export { computeBenchmarks }