Utils

Collection of useful utils for JavaScript/TypeScript projects. Some utilities are created for training and educational purposes.

Installation

# In Node.js
npm add @krutoo/utils

# In Deno
deno add npm:@krutoo/utils

# In Bun
bun add @krutoo/utils

Usage

Most of the utils are available from package root:

import { pairs } from '@krutoo/utils';

const list = [1, 2, 3];

for (const [a, b] of pairs(list)) {
  console.log(a, b);
}

// output:
// 1 2
// 1 3
// 2 3

React utils is available from /react path.

React must be installed in your project.

All React utilities, components and hooks are 100% SSR ready.

import { useMatchMedia } from '@krutoo/utils/react';

function App() {
  const isMobile = useMatchMedia('(max-width: 1024px)');

  return <>...</>;
}

Rspack utils is available from /rspack path.

Rspack must be installed in your project.

// rspack.config.js
import * as utils from '@krutoo/utils/rspack';

export default {
  entry: './src/index.ts',
  plugins: [
    // typescript support (with alias from "paths" of tsconfig and `resolve.alias` extending)
    utils.pluginTypeScript(),

    // css and css-modules support ("css-loader" must be added to your project)
    utils.pluginCSS(),

    // html file will be added to bundle
    utils.pluginHTML({ template: './src/index.html' }),

    // import file source code by `?raw` query or `with { type: 'text' }`
    utils.pluginRawImport(),

    // "public" folder will be copied to bundle
    utils.pluginPublicFiles(),

    // ...and other
  ],
};

Testing utils is available from /testing path.

import { ResizeObserverMock } from '@krutoo/utils/testing';

const mock = new ResizeObserverMock();

Development

Repo description and how to work with

File structure

• src folder contains files that will be compiled
• public folder contains files that will be added to package as is

Writing unit-tests

Test for module {path}/{module}.ts should be placed in {path}/__test__/{module}.test.ts.

By default test environment is just Node.js environment.

For write tests with simulating browser environment you need to name test file like *.web.test.ts.

Exports convention

Any exported file from this package should not contain default exports (export default ...). Defaults exports are hard to work with and less compatible between ESM and CJS.

Environment setup

First you need to use suitable Node.js version, for example by nvm:

nvm use && npm install

VSCode setup

This command will create/update .vscode/settings.json

npm run setup -- --vscode

Q&A

Notable info about this package

What is a custom sideEffects property in package.json?

This property need for bundlers like Webpack and Rspack that uses it for check that Tree Shaking is available.

Details here: https://webpack.js.org/guides/tree-shaking

TL;DR Side effects include:

• any function call on top level of module
• any mutation of imported variables on top level of module