codsen-utils^1.10.2

No 3rd party dependencies. All dependencies and devDependencies, checked recursively, are Codsen packages.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Classify individual characters
• Parse typed, short and repeatable CLI flags
• Assemble CLI help text
• Deeply clone a cyclic object graph
• Detect and resolve line endings
• Test whether a value exists
• Find overlapping substring occurrences
• Match a string against literal and regular-expression choices
• Intersect arrays in the first array's order
• Reject a character that is not a digit
• Omit keys and clone retained values
• Check own properties safely
• Distinguish plain objects from other object values
• Remove selected array values without mutating the input
• Remove one trailing slash
• Sort strings with the shared comparator
• Replace part of a string
• Reuse shared text symbols and HTML tag sets
• Trim selected characters from both string edges
• Check common JavaScript value types
• Deduplicate values while preserving order
• Match wildcard allow-lists and deny-lists

Idea

The small helpers that nearly every Codsen package needs: character classification, type guards, a few array and object utilities, EOL detection, wildcard matching and a CLI argument parser. They live here so that each of the other packages can depend on one place instead of on lodash, meow and friends.

Everything is a named export, so bundlers can tree-shake whatever you don’t use:

import { isNumberChar } from "codsen-utils";

console.log(isNumberChar("z"));
// => false
console.log(isNumberChar("0"));
// => true

This package is aimed at Codsen’s own programs first. The API is stable, but it grows to fit what those programs need.

API — character constants

Named constants for the characters which are easy to mistype and hard to spot in source code:

import { rawMDash, rightSingleQuote } from "codsen-utils";

console.log(`John${rightSingleQuote}s`);
// => "John’s"

API — character sets

import { inlineTags, voidTags } from "codsen-utils";

console.log(inlineTags.has("span"));
// => true
console.log(voidTags.includes("br"));
// => true

API — character checks

Each takes an unknown value and returns a boolean. None of them throw — a wrong type is simply false, so you can feed them str[i - 1] without checking whether the index exists.

isCurrencyChar() and isCurrencySymbol() differ only in length. Use the first when walking a string character by character, and the second when you already have a whole token:

import { isCurrencyChar, isCurrencySymbol } from "codsen-utils";

console.log(isCurrencyChar("CHF"));
// => false
console.log(isCurrencySymbol("CHF"));
// => true

API — type checks

import { existy, isPlainObject } from "codsen-utils";

console.log([isPlainObject({}), isPlainObject([]), isPlainObject(null)]);
// => [true, false, false]
console.log([existy(0), existy(null), existy(undefined)]);
// => [true, false, false]

isPlainObject() checks the container’s prototype, not whether its values are JSON-safe. Records can contain functions, undefined, bigint values, cycles, and symbol-keyed properties and still be plain objects. Use the exported JSONObject type only when your data already satisfies the JSON value contract.

API — array and object helpers

import { compareFn, omit, pullAll, uniq } from "codsen-utils";

console.log(pullAll([1, 2, 3, 4], [2, 4]));
// => [1, 3]
console.log(pullAll(undefined, undefined));
// => []
console.log(uniq([1, 1, 2, 3, 3]));
// => [1, 2, 3]
console.log(omit({ a: 1, b: 2, c: 3 }, ["b"]));
// => { a: 1, c: 3 }
console.log(["b", "a", "C"].sort(compareFn));
// => ["a", "b", "C"]

Deep-clone contract

deepClone() preserves cycles and repeated references inside the new graph. It supports arrays; plain and null-prototype records; dates; maps; sets; array buffers and views; regular expressions; errors; URLs; and ordinary class instances whose behaviour relies on cloneable own state. These built-in categories also work with cross-realm values. Primitive values and functions retain their identity.

Own __proto__ data stays an own property instead of changing the clone’s prototype, and null-prototype records remain null-prototype records. Enumerable accessors on records and arrays are read once and become data properties. Classes which depend on private fields or other hidden internal slots are outside the clone contract.

Use deepCloneWithMetadata() when you also need to know whether the source graph reused an object:

import { deepCloneWithMetadata } from "codsen-utils";

const shared = { enabled: true };
const result = deepCloneWithMetadata({ left: shared, right: shared });

console.log(result.hasRepeatedReferences);
// => true
console.log(result.value.left === result.value.right);
// => true
console.log(result.value.left === shared);
// => false

API — string helpers

import { findAllIdx, removeTrailingSlash, stringSplice } from "codsen-utils";

console.log(stringSplice("abcdef", 2, 3, "XY"));
// => "abXYf"
console.log(findAllIdx("scissors", "s"));
// => [0, 3, 4, 7]
console.log(removeTrailingSlash("a/b/"));
// => "a/b"

API — includes()

The function includes() is imported like this:

Like Array.prototype.includes(), but the array can hold a mix of strings and regexes, and it’s matched against a string. It’s a friendly API — it will not throw if the inputs are wrong:

import { includes } from "codsen-utils";

console.log(includes(["a", /^b/], "bcd"));
// => true
console.log(includes(["a"], "z"));
// => false

Only usable regular expressions participate. RegExp.prototype, proxies, and objects which only spoof the RegExp tag are ignored without throwing. Subclasses and cross-realm regular expressions work. A global expression starts and finishes with lastIndex set to 0; other expressions keep JavaScript’s native lastIndex behaviour.

API — match()

The function match() is imported like this:

Matches a whole string against one or more wildcard patterns:

The rules are:

• Patterns are anchored — they must consume the whole input, not a part of it.
• * stands for zero or more characters, and it does cross line breaks.
• A leading ! negates a pattern. Any negative pattern which matches vetoes the result outright, no matter what the positive ones did.
• Given only negative patterns, anything they don’t catch passes.
• An empty pattern array matches nothing.
• \ escapes the character after it, so \* means a literal asterisk and \\ means a literal backslash.
• Matching walks code points, not UTF-16 code units, so a wildcard can never consume half of a surrogate pair.

import { match } from "codsen-utils";

console.log(match("index.js", ["*.js", "!*.test.js"]));
// => true
console.log(match("index.test.js", ["*.js", "!*.test.js"]));
// => false
console.log(match("A.JS", ["*.js"], { caseSensitiveMatch: true }));
// => false

API — end of line

import { detectEol, resolveEolSetting } from "codsen-utils";

console.log(JSON.stringify(detectEol("a\r\nb")));
// => "\r\n"
console.log(JSON.stringify(resolveEolSetting("a\r\nb", "lf")));
// => "\n"
console.log(JSON.stringify(resolveEolSetting("a\r\nb", null)));
// => "\r\n"

That pairing is the point: resolveEolSetting() lets a program offer an explicit “write CRLF” option while still honouring whatever the input file already used when the caller says nothing.

API — codsenCLI()

The function codsenCLI() is imported like this:

An in-house stand-in for meow. It parses argv the way a CLI expects: flags with values, short flags, bundles, --no- negation, camelCase names and a -- escape hatch. It prints help or version on request.

The Options Object has the following shape:

Each entry under flags describes one flag:

The function returns a plain object:

For example:

import { codsenCLI } from "codsen-utils";

const cli = codsenCLI("Usage: mytool <file>", {
  pkg: { name: "mytool", version: "1.2.3", description: "Does a thing" },
  flags: {
    pad: { type: "boolean", shortFlag: "p" },
    name: { type: "string", default: "anon" },
    tag: { type: "string", isMultiple: true },
  },
  argv: ["a.txt", "-p", "--tag", "x", "--tag", "y"],
});

console.log(cli.input);
// => ["a.txt"]
console.log(cli.flags);
// => { pad: true, tag: ["x", "y"], name: "anon" }

--no- negation and the -- escape hatch work as you’d expect:

codsenCLI("h", { flags: { pad: { type: "boolean", default: true } }, argv: ["--no-pad"] }).flags;
// => { pad: false }

codsenCLI("h", { flags: {}, argv: ["a", "--", "--b"] }).input;
// => ["a", "--b"]

Number flags accept ordinary decimal and exponent spellings, including leading-dot values. Attached and separate values use the same grammar:

const flags = {
  ratio: { type: "number", shortFlag: "r" },
};

codsenCLI("h", { flags, argv: ["--ratio", "-.5"] }).flags.ratio;
// => -0.5

codsenCLI("h", { flags, argv: ["-r.5e2"] }).flags.ratio;
// => 50

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type {
  CliFlag,
  CliFlagType,
  CliOptions,
  CliPkg,
  CliResult,
  DeepCloneResult,
  EolChar,
  EolSetting,
  JSONArray,
  JSONObject,
  JSONValue,
  JsonObject,
  MatchOptions,
  Obj,
  PlainObject,
} from "codsen-utils";

Permalink to changelogChangelog