mixradix 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,284 @@
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { MixedRadix } from "./core/index.js";
+import { MixedRadixError } from "./errors/index.js";
+import { UsageError } from "./usage-error.js";
+const processIo = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+};
+const DESCRIPTION = "Add, subtract and convert integers of any size in mixed radix bases, where every digit position has its own radix.";
+const NOTATION_HELP = `bases:
+  One radix per digit position, most significant first, like a number.
+  10, 16          plain decimal, hexadecimal
+  24:60:60        hours:minutes:seconds, with days above that have no limit
+  24:60/wrap      a 24-hour clock that wraps around
+  2:3:4/repeat    the leftmost radix repeats: ...2:2:3:4
+
+  After '/', the overflow says what is left of the leftmost radix:
+  repeat (default for one radix), extend (default for several: one more
+  digit with no limit) or wrap (fixed width, values wrap around).
+
+numbers:
+  ff, 1011        one character per digit, in bases like 16 or 2
+  1:23:59         decimal digits separated by ':', in every base
+  45              in a base like 24:60:60, a single digit: 45 seconds`;
+const EXAMPLES = `examples:
+  mixradix add 23:59:59 1 -b 24:60:60      1:0:0:0
+  mixradix add 1:30 2:45 0:50 -b 60        5:5
+  mixradix sub 0:15 0:30 -b 24:60/wrap     23:45
+  mixradix convert 100000 -t 24:60:60      1:3:46:40
+  mixradix convert ff -b 16 -t 2           11111111
+  mixradix info 24:60:60`;
+const TOP_USAGE = "usage: mixradix [-h] [-V] COMMAND ...";
+const TOP_HELP = `${TOP_USAGE}
+
+${DESCRIPTION}
+
+commands:
+  add             Add numbers
+  sub (subtract)  Subtract every later number from the first
+  convert         Write a number in another base
+  info            Describe a base: overflow, place values and range
+
+options:
+  -h, --help      show this help message and exit
+  -V, --version   show program's version number and exit
+
+${NOTATION_HELP}
+
+${EXAMPLES}
+`;
+const HELP_OPTION = { help: { type: "boolean", short: "h" } };
+const JSON_OPTION = { json: { type: "boolean" } };
+const BASE_OPTIONS = {
+    base: { type: "string", short: "b", default: "10" },
+    to: { type: "string", short: "t" },
+};
+const calculate = (name, description) => ({
+    usage: `usage: mixradix ${name} [-h] [-b BASE] [-t TO] [--json] NUMBER [NUMBER ...]`,
+    description,
+    options: `options:
+  -h, --help       show this help message and exit
+  -b, --base BASE  base the numbers are written in (default: 10)
+  -t, --to TO      base to write the result in (default: --base)
+  --json           print the result as one line of JSON`,
+    config: { ...HELP_OPTION, ...BASE_OPTIONS, ...JSON_OPTION },
+});
+const COMMANDS = {
+    add: calculate("add", "Add numbers."),
+    sub: calculate("sub", "Subtract every later number from the first."),
+    convert: {
+        usage: "usage: mixradix convert [-h] [-b BASE] -t TO [--json] NUMBER",
+        description: "Write a number in another base.",
+        options: `options:
+  -h, --help       show this help message and exit
+  -b, --base BASE  base the number is written in (default: 10)
+  -t, --to TO      base to write the number in
+  --json           print the result as one line of JSON`,
+        config: { ...HELP_OPTION, ...BASE_OPTIONS, ...JSON_OPTION },
+    },
+    info: {
+        usage: "usage: mixradix info [-h] [--json] BASE",
+        description: "Describe a base: overflow, place values and range.",
+        options: `options:
+  -h, --help  show this help message and exit
+  --json      print the result as one line of JSON`,
+        config: { ...HELP_OPTION, ...JSON_OPTION },
+    },
+};
+const ALIASES = {
+    add: "add",
+    sub: "sub",
+    subtract: "sub",
+    convert: "convert",
+    info: "info",
+};
+// Short options. Any other argument starting with '-' and one more character,
+// like -5, -1:30 or -ff, is a negative number.
+const SHORT_OPTIONS = new Set(["b", "t", "h", "V", "-"]);
+/**
+ * Stops the option parser from reading negative numbers as options. A leading
+ * space makes an argument positional, and number parsing ignores it. After
+ * `--`, every argument is positional.
+ */
+function protectNegativeNumbers(argv) {
+    const result = [];
+    let restPositional = false;
+    for (const arg of argv) {
+        if (restPositional) {
+            result.push(arg.startsWith("-") ? ` ${arg}` : arg);
+        }
+        else if (arg === "--") {
+            restPositional = true;
+        }
+        else if (arg.length > 1 && arg[0] === "-" && !SHORT_OPTIONS.has(arg[1])) {
+            result.push(` ${arg}`);
+        }
+        else {
+            result.push(arg);
+        }
+    }
+    return result;
+}
+/** Runs the CLI with `argv` (without the node and script paths) and returns the exit code. */
+export function main(argv = process.argv.slice(2), io = processIo) {
+    try {
+        return run(protectNegativeNumbers(argv), io);
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            io.stderr(`${e.usage}\n${e.prog}: error: ${e.message}\n`);
+            return 2;
+        }
+        if (e instanceof MixedRadixError) {
+            io.stderr(`error: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function run(args, io) {
+    const [first, ...rest] = args;
+    if (first === "-h" || first === "--help") {
+        io.stdout(TOP_HELP);
+        return 0;
+    }
+    if (first === "-V" || first === "--version") {
+        io.stdout(`mixradix ${version()}\n`);
+        return 0;
+    }
+    if (first === undefined) {
+        throw new UsageError(TOP_USAGE, "mixradix", "the following arguments are required: COMMAND");
+    }
+    const name = ALIASES[first];
+    if (name === undefined) {
+        throw new UsageError(TOP_USAGE, "mixradix", `argument COMMAND: invalid choice: '${first.trim()}' (choose from add, sub, subtract, convert, info)`);
+    }
+    const command = COMMANDS[name];
+    const prog = `mixradix ${first}`;
+    const usageError = (message) => new UsageError(command.usage, prog, message);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: command.config,
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (e) {
+        throw usageError(e instanceof Error ? e.message : String(e));
+    }
+    const values = parsed.values;
+    const positionals = parsed.positionals.map((p) => p.trim());
+    if (values.help) {
+        io.stdout(`${command.usage}\n\n${command.description}\n\n${command.options}\n\n${NOTATION_HELP}\n`);
+        return 0;
+    }
+    const json = values.json ?? false;
+    if (name === "info") {
+        const [baseText, ...extra] = positionals;
+        if (baseText === undefined)
+            throw usageError("the following arguments are required: BASE");
+        if (extra.length > 0)
+            throw usageError(`unrecognized arguments: ${extra.join(" ")}`);
+        const base = new MixedRadix(baseText);
+        io.stdout(`${json ? infoJson(base) : infoText(base)}\n`);
+        return 0;
+    }
+    const base = new MixedRadix((values.base ?? "10").trim());
+    const to = values.to === undefined ? undefined : new MixedRadix(values.to.trim());
+    let result;
+    if (name === "convert") {
+        const [numberText, ...extra] = positionals;
+        if (to === undefined)
+            throw usageError("the following arguments are required: -t/--to");
+        if (numberText === undefined)
+            throw usageError("the following arguments are required: NUMBER");
+        if (extra.length > 0)
+            throw usageError(`unrecognized arguments: ${extra.join(" ")}`);
+        result = base.parse(numberText);
+    }
+    else {
+        if (positionals.length === 0)
+            throw usageError("the following arguments are required: NUMBER");
+        if (positionals.length < 2)
+            throw usageError("at least two numbers are required");
+        const [head, ...tail] = positionals.map((p) => base.parse(p));
+        result = tail.reduce((acc, n) => (name === "sub" ? acc.sub(n) : acc.add(n)), head);
+    }
+    if (to !== undefined)
+        result = result.to(to);
+    io.stdout(`${json ? numberJson(result) : result.toString()}\n`);
+    return 0;
+}
+function version() {
+    const path = new URL("../package.json", import.meta.url);
+    return JSON.parse(readFileSync(path, "utf8")).version;
+}
+/** Compact JSON where bigints are written as plain JSON numbers of any size. */
+function toJson(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return `[${value.map(toJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value).map(([k, v]) => `${JSON.stringify(k)}:${toJson(v)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function numberJson(number) {
+    return toJson({
+        result: number.toString(),
+        value: number.value,
+        digits: [...number.digits],
+        negative: number.isNegative,
+        base: number.base.toString(),
+    });
+}
+/** Place values shown by `info`, most significant first. */
+function placeValues(base) {
+    const count = base.radices.length;
+    const shown = { extend: count + 1, wrap: count, repeat: Math.max(count + 1, 4) }[base.overflow];
+    return Array.from({ length: shown }, (_, i) => base.placeValue(shown - 1 - i));
+}
+function infoJson(base) {
+    return toJson({
+        base: base.toString(),
+        radices: [...base.radices],
+        overflow: base.overflow,
+        max_digits: base.maxDigits,
+        place_values: placeValues(base),
+        modulus: base.modulus,
+    });
+}
+function infoText(base) {
+    let places = placeValues(base).join(", ");
+    const modulus = base.modulus;
+    let overflow;
+    let digits;
+    if (base.overflow === "extend") {
+        overflow = "extend (the leftmost digit has no limit)";
+        digits = `at most ${base.maxDigits}`;
+    }
+    else if (modulus !== null) {
+        overflow = `wrap (values wrap around modulo ${modulus})`;
+        digits = `exactly ${base.maxDigits}`;
+    }
+    else {
+        overflow = `repeat (positions further left use radix ${base.radices[0]})`;
+        digits = "any number";
+        places = `..., ${places}`;
+    }
+    const lines = [
+        ["base", base.toString()],
+        ["overflow", overflow],
+        ["digits", digits],
+        ["place values", places],
+    ];
+    if (modulus !== null)
+        lines.push(["range", `0 to ${modulus - 1n}`]);
+    return lines.map(([label, value]) => `${label}:`.padEnd(14) + value).join("\n");
+}

package/dist/core/common.d.ts

@@ -0,0 +1,18 @@
+/** What is left of the leftmost radix: see the README. */
+export type Overflow = "extend" | "wrap" | "repeat";
+export declare const SEPARATOR = ":";
+export declare const OVERFLOW_SEPARATOR = "/";
+export declare const DIGIT_CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+export declare const MAX_COMPACT_RADIX: bigint;
+export declare const BASE_SYNTAX = "expected radices of 2 or more separated by ':', like 16 or 24:60:60";
+export declare const DIGIT_SYNTAX = "expected decimal digits separated by ':'";
+export declare const isDecimal: (text: string) => boolean;
+export declare const defaultOverflow: (radixCount: number) => Overflow;
+export declare const listLabel: (values: readonly unknown[]) => string;
+export declare function checkOverflow(base: string, overflow: string): Overflow;
+/** A safe integer or bigint as a bigint, or undefined for anything else. */
+export declare function asInteger(value: unknown): bigint | undefined;
+export declare function toInteger(value: number | bigint): bigint;
+export declare const abs: (value: bigint) => bigint;
+/** Remainder that is never negative, for wrapping values into [0, modulus). */
+export declare const mod: (value: bigint, modulus: bigint) => bigint;

package/dist/core/common.js

@@ -0,0 +1,37 @@
+/** Notation and integer helpers shared by MixedRadix and MixedRadixNumber. */
+import { InvalidBaseError } from "../errors/index.js";
+const OVERFLOWS = ["extend", "wrap", "repeat"];
+export const SEPARATOR = ":";
+export const OVERFLOW_SEPARATOR = "/";
+export const DIGIT_CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+export const MAX_COMPACT_RADIX = BigInt(DIGIT_CHARS.length);
+export const BASE_SYNTAX = "expected radices of 2 or more separated by ':', like 16 or 24:60:60";
+export const DIGIT_SYNTAX = "expected decimal digits separated by ':'";
+export const isDecimal = (text) => /^[0-9]+$/.test(text);
+export const defaultOverflow = (radixCount) => radixCount === 1 ? "repeat" : "extend";
+export const listLabel = (values) => `[${values.map(String).join(", ")}]`;
+export function checkOverflow(base, overflow) {
+    const known = OVERFLOWS.find((o) => o === overflow);
+    if (known === undefined) {
+        throw new InvalidBaseError(base, `unknown overflow '${overflow}' (expected extend, wrap or repeat)`);
+    }
+    return known;
+}
+/** A safe integer or bigint as a bigint, or undefined for anything else. */
+export function asInteger(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return BigInt(value);
+    return undefined;
+}
+export function toInteger(value) {
+    const integer = asInteger(value);
+    if (integer === undefined) {
+        throw new TypeError(`expected a safe integer or a bigint, got ${String(value)}`);
+    }
+    return integer;
+}
+export const abs = (value) => (value < 0n ? -value : value);
+/** Remainder that is never negative, for wrapping values into [0, modulus). */
+export const mod = (value, modulus) => ((value % modulus) + modulus) % modulus;

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export type { Overflow } from "./common.js";
+export { type BaseLike, type BaseOptions, MixedRadix } from "./mixed-radix.js";
+export { MixedRadixNumber, type NumberLike } from "./mixed-radix-number.js";

package/dist/core/index.js

@@ -0,0 +1,2 @@
+export { MixedRadix } from "./mixed-radix.js";
+export { MixedRadixNumber } from "./mixed-radix-number.js";

package/dist/core/mixed-radix-number.d.ts

@@ -0,0 +1,34 @@
+import { type BaseLike, MixedRadix } from "./mixed-radix.js";
+/** An operand for arithmetic: a number, an integer, or text in the left operand's base. */
+export type NumberLike = MixedRadixNumber | string | number | bigint;
+/**
+ * A signed integer of any size, written in a MixedRadix.
+ *
+ * Arithmetic is on values, so operands may be in different bases, integers,
+ * or text in this number's base. Results use the left operand's base.
+ *
+ * ```ts
+ * new MixedRadixNumber("23:59:59", "24:60:60").add(1).toString(); // "1:0:0:0"
+ * ```
+ */
+export declare class MixedRadixNumber {
+    readonly value: bigint;
+    readonly base: MixedRadix;
+    constructor(number: string | number | bigint, base?: BaseLike);
+    get isNegative(): boolean;
+    /** Digit values of the absolute value, most significant first. */
+    get digits(): readonly bigint[];
+    /** The same value written in another base. */
+    to(base: BaseLike): MixedRadixNumber;
+    add(other: NumberLike): MixedRadixNumber;
+    sub(other: NumberLike): MixedRadixNumber;
+    neg(): MixedRadixNumber;
+    abs(): MixedRadixNumber;
+    /** -1, 0 or 1 as this value is below, equal to or above `other`'s. */
+    compare(other: MixedRadixNumber | number | bigint): -1 | 0 | 1;
+    /** True when the values are equal, whatever the bases. */
+    equals(other: MixedRadixNumber | number | bigint): boolean;
+    toBigInt(): bigint;
+    toString(): string;
+    toJSON(): string;
+}

package/dist/core/mixed-radix-number.js

@@ -0,0 +1,111 @@
+import { abs, DIGIT_CHARS, mod, SEPARATOR, toInteger } from "./common.js";
+import { MixedRadix } from "./mixed-radix.js";
+/**
+ * A signed integer of any size, written in a MixedRadix.
+ *
+ * Arithmetic is on values, so operands may be in different bases, integers,
+ * or text in this number's base. Results use the left operand's base.
+ *
+ * ```ts
+ * new MixedRadixNumber("23:59:59", "24:60:60").add(1).toString(); // "1:0:0:0"
+ * ```
+ */
+export class MixedRadixNumber {
+    value;
+    base;
+    constructor(number, base = 10) {
+        const mixedRadix = MixedRadix.of(base);
+        const built = typeof number === "string" ? mixedRadix.parse(number) : mixedRadix.fromInt(number);
+        this.value = built.value;
+        this.base = mixedRadix;
+        Object.freeze(this);
+    }
+    /** @internal Makes a number from a value, wrapping it for `wrap` bases. */
+    static create(value, base) {
+        const modulus = base.modulus;
+        const number = Object.create(MixedRadixNumber.prototype);
+        Object.assign(number, { value: modulus === null ? value : mod(value, modulus), base });
+        return Object.freeze(number);
+    }
+    get isNegative() {
+        return this.value < 0n;
+    }
+    /** Digit values of the absolute value, most significant first. */
+    get digits() {
+        let remaining = abs(this.value);
+        const digits = []; // least significant first while building
+        if (this.base.overflow === "wrap") {
+            for (let i = this.base.radices.length - 1; i >= 0; i--) {
+                const radix = this.base.radices[i];
+                digits.push(remaining % radix);
+                remaining /= radix;
+            }
+        }
+        else {
+            for (let position = 0;; position++) {
+                const radix = this.base.radixAt(position);
+                if (radix === null) {
+                    digits.push(remaining);
+                    break;
+                }
+                digits.push(remaining % radix);
+                remaining /= radix;
+                if (remaining === 0n)
+                    break;
+            }
+        }
+        return Object.freeze(digits.reverse());
+    }
+    /** The same value written in another base. */
+    to(base) {
+        return MixedRadixNumber.create(this.value, MixedRadix.of(base));
+    }
+    // -- Arithmetic --------------------------------------------------------------
+    add(other) {
+        return MixedRadixNumber.create(this.value + operandValue(this, other), this.base);
+    }
+    sub(other) {
+        return MixedRadixNumber.create(this.value - operandValue(this, other), this.base);
+    }
+    neg() {
+        return MixedRadixNumber.create(-this.value, this.base);
+    }
+    abs() {
+        return MixedRadixNumber.create(abs(this.value), this.base);
+    }
+    // -- Comparison (by value) -----------------------------------------------------
+    /** -1, 0 or 1 as this value is below, equal to or above `other`'s. */
+    compare(other) {
+        const value = other instanceof MixedRadixNumber ? other.value : toInteger(other);
+        return this.value < value ? -1 : this.value > value ? 1 : 0;
+    }
+    /** True when the values are equal, whatever the bases. */
+    equals(other) {
+        return this.compare(other) === 0;
+    }
+    // -- Conversion ------------------------------------------------------------------
+    toBigInt() {
+        return this.value;
+    }
+    toString() {
+        const sign = this.value < 0n ? "-" : "";
+        const digits = this.digits;
+        if (this.base.isUniform)
+            return sign + digits.map((d) => DIGIT_CHARS[Number(d)]).join("");
+        return sign + digits.join(SEPARATOR);
+    }
+    toJSON() {
+        return this.toString();
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `MixedRadixNumber('${this}', base='${this.base}')`;
+    }
+}
+/** The value of an arithmetic operand; text is parsed in the left operand's base. */
+function operandValue(left, other) {
+    if (other instanceof MixedRadixNumber)
+        return other.value;
+    if (typeof other === "string")
+        return left.base.parse(other).value;
+    return toInteger(other);
+}

package/dist/core/mixed-radix.d.ts

@@ -0,0 +1,60 @@
+import { type Overflow } from "./common.js";
+import { MixedRadixNumber } from "./mixed-radix-number.js";
+/** Anything that can be turned into a base: `"24:60:60"`, `16`, `[24, 60, 60]`. */
+export type BaseLike = MixedRadix | string | number | bigint | readonly (number | bigint)[];
+export interface BaseOptions {
+    overflow?: Overflow;
+}
+/**
+ * A base with one radix per digit position, most significant first.
+ *
+ * ```ts
+ * const time = new MixedRadix("24:60:60");
+ * time.parse("1:23:59").value; // 5039n
+ * new MixedRadix(16).fromInt(255).toString(); // "ff"
+ * ```
+ */
+export declare class MixedRadix {
+    #private;
+    /** The written radices, most significant first (normalized). */
+    readonly radices: readonly bigint[];
+    readonly overflow: Overflow;
+    constructor(base: string | number | bigint | readonly (number | bigint)[], options?: BaseOptions);
+    /** Returns `base` itself if it is a MixedRadix, otherwise builds one. */
+    static of(base: BaseLike): MixedRadix;
+    /**
+     * True for one radix of at most 36 that never has an unlimited digit, so
+     * numbers can be written one character per digit (`ff`, `1011`).
+     */
+    get isUniform(): boolean;
+    /** How many digits a number can have, or null for no limit. */
+    get maxDigits(): number | null;
+    /** The product of all radices for `wrap`, otherwise null. */
+    get modulus(): bigint | null;
+    /**
+     * Radix of a digit position (0 = least significant).
+     *
+     * Returns null for the unlimited leading digit of `extend`, and throws a
+     * RangeError for a position the base doesn't have.
+     */
+    radixAt(position: number): bigint | null;
+    /** What a 1 at `position` is worth: the product of the radices below it. */
+    placeValue(position: number): bigint;
+    /** Parses `"1:23:59"`, `"-ff"`, `"45"` and so on in this base. */
+    parse(text: string): MixedRadixNumber;
+    /** The integer `value` in this base. */
+    fromInt(value: number | bigint): MixedRadixNumber;
+    /**
+     * A number from digit values, most significant first.
+     *
+     * ```ts
+     * new MixedRadix("24:60:60").fromDigits([1, 23, 59]).toString(); // "1:23:59"
+     * ```
+     */
+    fromDigits(digits: readonly (number | bigint)[], options?: {
+        negative?: boolean;
+    }): MixedRadixNumber;
+    equals(other: MixedRadix): boolean;
+    toString(): string;
+    toJSON(): string;
+}