arithcode 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aqu3180
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# arithcode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Arithmetic coding + String coder

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+export declare function frac(num: number | bigint, den: number | bigint): Fraction;
+export declare function frac(value: number | bigint | Fraction): Fraction;
+export declare class Fraction {
+  private static readonly view;
+  static commonDenominator(a: Fraction, b: Fraction): {
+    den: bigint;
+    a: bigint;
+    b: bigint;
+  };
+  num: bigint;
+  den: bigint;
+  constructor(num: number | bigint, den: number | bigint);
+  constructor(value: number | bigint | Fraction);
+  isLessThan(b: Fraction): boolean;
+  isGreaterThan(b: Fraction): boolean;
+  isLessThanOrEqualTo(b: Fraction): boolean;
+  isGreaterThanOrEqualTo(b: Fraction): boolean;
+  reduce(): void;
+  toReduced(): Fraction;
+  toString(): string;
+}
+export declare class ArithmeticRange {
+  den: bigint;
+  low: bigint;
+  high: bigint;
+  constructor(den?: bigint, low?: bigint, high?: bigint);
+  get isValid(): boolean;
+  get denAbs(): bigint;
+  get lowAbs(): bigint;
+  get highAbs(): bigint;
+  toString(): string;
+}
+export declare class ArithmeticValue extends Fraction {
+  get isValid(): boolean;
+  get denAbs(): bigint;
+  get numAbs(): bigint;
+}
+export declare abstract class StringCoder {
+  abstract encode(range: ArithmeticRange): string;
+  abstract decode(code: string): ArithmeticValue;
+}
+export declare abstract class DigitCoder extends StringCoder {
+  protected abstract charMap: string;
+  encode(range: ArithmeticRange): string;
+  decode(code: string): ArithmeticValue;
+}
+export declare class Base64Coder extends DigitCoder {
+  protected charMap: string;
+}
+export declare const BASE64_CODER: Base64Coder;
+export declare class Base64UrlCoder extends DigitCoder {
+  protected charMap: string;
+}
+export declare const BASE64URL_CODER: Base64UrlCoder;
+export declare class Z85Coder extends DigitCoder {
+  protected charMap: string;
+}
+export declare const Z85_CODER: Z85Coder;
+export declare class Base94Coder extends DigitCoder {
+  protected charMap: string;
+}
+export declare const BASE94_CODER: Base94Coder;
+export interface DistributionLike<T = number[]> {
+  encode(input: T): ArithmeticRange;
+  decode(value: ArithmeticValue): T;
+}
+export type DistributionInput<T extends DistributionLike<unknown>> = T extends DistributionLike<infer I> ? I : never;
+export declare class Protocol<T extends DistributionLike<unknown> = Distribution> {
+  distribution: T;
+  coder: StringCoder;
+  constructor(distribution: T, coder: StringCoder);
+  encode(data: DistributionInput<T>): string;
+  decode(code: string): DistributionInput<T>;
+}
+type _TupleIndicesRecursive<T extends unknown[], R extends unknown[]> = T['length'] extends R['length'] ? R[number] : _TupleIndicesRecursive<T, [...R, R['length']]>;
+type TupleIndices<T extends unknown[]> = number extends T['length'] ? number : _TupleIndicesRecursive<T, []>;
+export declare abstract class Distribution implements DistributionLike {
+  private currentInput;
+  private currentOutput;
+  private currentArrIdx;
+  encode(data: number[]): ArithmeticRange;
+  decode(value: Fraction): number[];
+  private encodeRange;
+  private decodeRange;
+  /**
+   * @example
+   * class MyDistribution extends Distribution {
+   *   protected override distribution() {
+   *     const kind = this.range([
+   *       // Vegetables
+   *       frac(1, 5),
+   *       // Fast foods
+   *       frac(2, 3),
+   *       // Fruits
+   *     ])
+   *     if (kind === 2) {
+   *       const fruit = this.range([
+   *         // Apple
+   *         0.25,
+   *         // Banana
+   *         0.625,
+   *         // Orange
+   *         0.75,
+   *         // Strawberry
+   *       ])
+   *       // ...
+   *     }
+   *   }
+   * }
+   */
+  protected range<const T extends readonly (number | Fraction)[]>(range: T): TupleIndices<[0, ...T]>;
+  /**
+   * @example
+   * class MyDistribution extends Distribution {
+   *   protected override distribution() {
+   *     this.range([0.333, 0.667])
+   *     this.range([frac(1, 3), frac(2, 3)])
+   *     // ...
+   *   }
+   *   // ...
+   * }
+   */
+  protected abstract distribution(): void;
+}
+export declare abstract class Serializer<T> implements DistributionLike<T> {
+  readonly distribution: Distribution;
+  constructor(distribution: Distribution);
+  encode(input: T): ArithmeticRange;
+  decode(value: ArithmeticValue): T;
+  protected abstract serialize(input: T): number[];
+  protected abstract deserialize(serialized: number[]): T;
+}
+export {};

package/dist/index.mjs

@@ -0,0 +1,386 @@
+// src/utils.ts
+function isPositiveIntPowerOfTwo(positiveInt) {
+	return !(positiveInt & positiveInt - 1n);
+}
+function gcd(a, b) {
+	a = abs(a);
+	b = abs(b);
+	if (a < b) [a, b] = [b, a];
+	while (b) [a, b] = [b, a % b];
+	return a;
+}
+function ceilFraction(num, den) {
+	return (num > 0n && den > 0n || num < 0n && den < 0n) && num % den ? num / den + 1n : num / den;
+}
+function abs(v) {
+	return v < 0n ? -v : v;
+}
+// src/fraction.ts
+function frac(a, b) {
+	return new Fraction(a, b);
+}
+var Fraction = class Fraction {
+	static view = /* @__PURE__ */ new DataView(/* @__PURE__ */ new ArrayBuffer(8));
+	static commonDenominator(a, b) {
+		if (!a.den || !b.den) throw RangeError(`Division by zero (getting commonDenominator of ${a} and ${b})`);
+		let den, aCommonNum, bCommonNum;
+		const aSign = a.den < 0n ? -1n : 1n;
+		const aNum = a.num * aSign;
+		const aDen = a.den * aSign;
+		const bSign = b.den < 0n ? -1n : 1n;
+		const bNum = b.num * bSign;
+		const bDen = b.den * bSign;
+		if (isPositiveIntPowerOfTwo(aDen) && isPositiveIntPowerOfTwo(bDen)) {
+			if (aDen > bDen) {
+				den = aDen;
+				aCommonNum = aNum;
+				bCommonNum = aDen / bDen * bNum;
+			} else {
+				den = bDen;
+				aCommonNum = bDen / aDen * aNum;
+				bCommonNum = bNum;
+			}
+		} else {
+			const gcdValue = gcd(aDen, bDen);
+			den = aDen / gcdValue * bDen;
+			aCommonNum = bDen / gcdValue * aNum;
+			bCommonNum = aDen / gcdValue * bNum;
+		}
+		return {
+			den,
+			a: aCommonNum,
+			b: bCommonNum
+		};
+	}
+	num;
+	den;
+	constructor(a, b) {
+		if (b !== void 0) {
+			this.num = BigInt(a);
+			this.den = BigInt(b);
+			return;
+		}
+		if (typeof a == "bigint" || Number.isInteger(a)) {
+			this.num = BigInt(a);
+			this.den = 1n;
+			return;
+		}
+		if (a instanceof Fraction) {
+			this.num = a.num;
+			this.den = a.den;
+			return;
+		}
+		if (!Number.isFinite(a)) throw TypeError("Only finite numbers can be converted to fraction; received " + a);
+		Fraction.view.setFloat64(0, a);
+		const bits = Fraction.view.getBigUint64(0);
+		const sign = bits >> 63n ? -1n : 1n;
+		const exponent = bits >> 52n & 2047n;
+		const fraction = bits & 4503599627370495n;
+		let num = sign * (exponent ? 4503599627370496n | fraction : fraction);
+		let log2den = exponent ? 1075n - exponent : 1074n;
+		while (log2den && !(num & 1n)) {
+			num >>= 1n;
+			log2den -= 1n;
+		}
+		this.num = num;
+		this.den = 2n ** log2den;
+	}
+	isLessThan(b) {
+		if (!this.den || !b.den) throw RangeError(`Division by zero (checking isLessThan for ${this} and ${b})`);
+		const aSign = this.den < 0n ? -1n : 1n;
+		const aNum = this.num * aSign;
+		const aDen = this.den * aSign;
+		const bSign = b.den < 0n ? -1n : 1n;
+		const bNum = b.num * bSign;
+		return aNum * (b.den * bSign) < bNum * aDen;
+	}
+	isGreaterThan(b) {
+		if (!this.den || !b.den) throw RangeError(`Division by zero (checking isGreaterThan for ${this} and ${b})`);
+		return b.isLessThan(this);
+	}
+	isLessThanOrEqualTo(b) {
+		if (!this.den || !b.den) throw RangeError(`Division by zero (checking isLessThanOrEqualTo for ${this} and ${b})`);
+		return !b.isLessThan(this);
+	}
+	isGreaterThanOrEqualTo(b) {
+		if (!this.den || !b.den) throw RangeError(`Division by zero (checking isGreaterThanOrEqualTo for ${this} and ${b})`);
+		return !this.isLessThan(b);
+	}
+	reduce() {
+		const gcdValue = gcd(this.num, this.den);
+		this.num /= gcdValue;
+		this.den /= gcdValue;
+	}
+	toReduced() {
+		const gcdValue = gcd(this.num, this.den);
+		return new Fraction(this.num / gcdValue, this.den / gcdValue);
+	}
+	toString() {
+		return `${this.num}/${this.den}`;
+	}
+};
+// src/values.ts
+var ArithmeticRange = class {
+	den;
+	low;
+	high;
+	constructor(den = 1n, low = 0n, high = den) {
+		this.den = den;
+		this.low = low;
+		this.high = high;
+	}
+	get isValid() {
+		const sign = this.den < 0n ? -1n : 1n;
+		const den = this.den * sign;
+		const low = this.low * sign;
+		const high = this.high * sign;
+		return 0n <= low && low < high && high <= den;
+	}
+	get denAbs() {
+		if (!this.isValid) throw RangeError(`Cannot get ArithmeticRange.denAbs when not valid (received ${this})`);
+		return abs(this.den);
+	}
+	get lowAbs() {
+		if (!this.isValid) throw RangeError(`Cannot get ArithmeticRange.lowAbs when not valid (received ${this})`);
+		return abs(this.low);
+	}
+	get highAbs() {
+		if (!this.isValid) throw RangeError(`Cannot get ArithmeticRange.highAbs when not valid (received ${this})`);
+		return abs(this.high);
+	}
+	toString() {
+		return `${this.low} ~ ${this.high} / ${this.den}`;
+	}
+};
+var ArithmeticValue = class extends Fraction {
+	get isValid() {
+		const sign = this.den < 0n ? -1n : 1n;
+		const num = this.num * sign;
+		const den = this.den * sign;
+		return den !== 0n && 0n <= num && num <= den;
+	}
+	get denAbs() {
+		if (!this.isValid) throw RangeError(`Cannot get ArithmeticValue.denAbs when not valid (received ${this})`);
+		return abs(this.den);
+	}
+	get numAbs() {
+		if (!this.isValid) throw RangeError(`Cannot get ArithmeticValue.numAbs when not valid (received ${this})`);
+		return abs(this.num);
+	}
+};
+// src/distribution.ts
+const zeroFraction = new ArithmeticValue(0n);
+const oneFraction = new ArithmeticValue(1n);
+var Distribution = class {
+	currentInput = null;
+	currentOutput = null;
+	currentArrIdx = 0;
+	encode(data) {
+		try {
+			const output = new ArithmeticRange();
+			this.currentInput = data;
+			this.currentOutput = output;
+			this.currentArrIdx = 0;
+			this.distribution();
+			const expectedLength = this.currentArrIdx;
+			const actualLength = data.length;
+			if (expectedLength !== actualLength) throw RangeError(`Too large encoding input (the expected input length was ${expectedLength}, received ${actualLength})`);
+			return output;
+		} finally {
+			this.currentInput = null;
+			this.currentOutput = null;
+			this.currentArrIdx = 0;
+		}
+	}
+	decode(value) {
+		try {
+			const output = [];
+			this.currentInput = new ArithmeticValue(value);
+			this.currentOutput = output;
+			this.distribution();
+			return output;
+		} finally {
+			this.currentInput = null;
+			this.currentOutput = null;
+		}
+	}
+	encodeRange(i, fractionRange) {
+		const range = this.currentOutput;
+		const low = fractionRange[i - 1] ?? zeroFraction;
+		const high = fractionRange[i] ?? oneFraction;
+		const { den: reducedDen, a: reducedLow, b: reducedHigh } = Fraction.commonDenominator(low, high);
+		if (reducedLow === reducedHigh) throw RangeError(`Invalid encoding input data at index ${this.currentArrIdx}: the distribution range of ${i} has zero size`);
+		const distancePer1 = range.high - range.low;
+		range.den *= reducedDen;
+		range.low *= reducedDen;
+		range.high *= reducedDen;
+		range.high = range.low + distancePer1 * reducedHigh;
+		range.low = range.low + distancePer1 * reducedLow;
+	}
+	decodeRange(value, fractionRange) {
+		const output = this.currentOutput;
+		let matchedIdx = fractionRange.length;
+		let matchedPrev = fractionRange[matchedIdx - 1] ?? zeroFraction;
+		let matchedCurrent = oneFraction;
+		let prev = zeroFraction;
+		for (let i = 0; i < fractionRange.length; ++i) {
+			const current = fractionRange[i];
+			try {
+				if (value.isGreaterThanOrEqualTo(current) || prev.isGreaterThan(value)) continue;
+				matchedIdx = i;
+				matchedPrev = prev;
+				matchedCurrent = current;
+				break;
+			} finally {
+				prev = current;
+			}
+		}
+		const { den, a, b } = Fraction.commonDenominator(matchedPrev, matchedCurrent);
+		value.num = value.num * den - a * value.den;
+		value.den *= b - a;
+		output.push(matchedIdx);
+		return matchedIdx;
+	}
+	/**
+	* @example
+	* class MyDistribution extends Distribution {
+	*   protected override distribution() {
+	*     const kind = this.range([
+	*       // Vegetables
+	*       frac(1, 5),
+	*       // Fast foods
+	*       frac(2, 3),
+	*       // Fruits
+	*     ])
+	*     if (kind === 2) {
+	*       const fruit = this.range([
+	*         // Apple
+	*         0.25,
+	*         // Banana
+	*         0.625,
+	*         // Orange
+	*         0.75,
+	*         // Strawberry
+	*       ])
+	*       // ...
+	*     }
+	*   }
+	* }
+	*/
+	range(range) {
+		if (this.currentInput === null) throw TypeError("Cannot call Distribution.range() when idle state");
+		const fractionRange = range.map((v) => new ArithmeticValue(v));
+		fractionRange.forEach((v, i) => {
+			if (!v.isValid) throw RangeError(`Invalid distribution edge at index ${i}: ${v} is out of range 0 ~ 1 (provided ${range.join(", ")})`);
+			if (i === 0) return;
+			const prev = fractionRange[i - 1];
+			if (prev.isGreaterThan(v)) throw TypeError(`Invalid distribution edges at index ${i - 1} / ${i}: ${prev} > ${v} (provided ${range.join(", ")})`);
+		});
+		if (Array.isArray(this.currentInput)) {
+			const i = this.currentInput[this.currentArrIdx];
+			if (i === void 0) throw RangeError(`Too small encoding input (received (${this.currentInput.length}) [${this.currentInput.join(", ")}])`);
+			if (!Number.isInteger(i) || i < 0 || fractionRange.length < i) throw RangeError(`Invalid encoding input data at index ${this.currentArrIdx}: expected integer between 0 ~ ${fractionRange.length}, received ${i}`);
+			this.encodeRange(i, fractionRange);
+			++this.currentArrIdx;
+			return i;
+		} else {
+			const value = this.currentInput;
+			if (!value.isValid) throw RangeError(`Decoding input is out of range 0 ~ 1 (received ${value})`);
+			return this.decodeRange(value, fractionRange);
+		}
+	}
+};
+// src/serializer.ts
+var Serializer = class {
+	distribution;
+	constructor(distribution) {
+		this.distribution = distribution;
+	}
+	encode(input) {
+		return this.distribution.encode(this.serialize(input));
+	}
+	decode(value) {
+		return this.deserialize(this.distribution.decode(value));
+	}
+};
+// src/string-coder.ts
+var StringCoder = class {};
+var DigitCoder = class extends StringCoder {
+	encode(range) {
+		if (!range.isValid) throw RangeError(`Invalid range input: ${range}`);
+		let { lowAbs: low, highAbs: high } = range;
+		const { denAbs: den } = range;
+		if (low * 2n <= den && den < high * 2n) return "";
+		const charMap = this.charMap;
+		const digits = BigInt(charMap.length);
+		let code = "";
+		const den2 = den * 2n;
+		const den3 = den * 3n;
+		for (;;) {
+			const lowNum = low * digits;
+			const highNum = high * digits;
+			const lowCeil = ceilFraction(lowNum * 2n - den, den2);
+			const highCeil = ceilFraction(highNum * 2n - den3, den2);
+			if (lowCeil < 0n || digits < lowCeil || highCeil < -1n || digits <= highCeil) throw RangeError(`Low or high value is out of range (${lowCeil} ~ ${highCeil} / ${digits}). This is an internal bug in DigitCoder.encode() method.`);
+			if (lowCeil <= highCeil) {
+				code += charMap[Number(highCeil)];
+				break;
+			}
+			const divNum = den * lowCeil;
+			const preferredCeil = divNum - lowNum <= highNum - divNum ? lowCeil : highCeil;
+			if (preferredCeil < 0n || digits <= preferredCeil) throw RangeError(`preferredCeil is out of range (${preferredCeil} / ${digits}). This is an internal bug in DigitCoder.encode() method.`);
+			code += charMap[Number(preferredCeil)];
+			low = lowNum - preferredCeil * den;
+			high = highNum - preferredCeil * den;
+			if (low < 0n) low = 0n;
+			if (high > den) high = den;
+		}
+		return code;
+	}
+	decode(code) {
+		const charMap = this.charMap;
+		const digits = BigInt(charMap.length);
+		let num = 1n;
+		let den = 2n;
+		for (let i = 0; i < code.length; ++i) {
+			const char = code[i];
+			const charIdx = charMap.indexOf(char);
+			if (charIdx === -1) throw TypeError("Invalid char received: " + char);
+			num = (num - 1n) * digits + BigInt(charIdx * 2 + 1);
+			den *= digits;
+		}
+		return new ArithmeticValue(num, den);
+	}
+};
+var Base64Coder = class extends DigitCoder {
+	charMap = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+};
+const BASE64_CODER = new Base64Coder();
+var Base64UrlCoder = class extends DigitCoder {
+	charMap = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+};
+const BASE64URL_CODER = new Base64UrlCoder();
+var Z85Coder = class extends DigitCoder {
+	charMap = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
+};
+const Z85_CODER = new Z85Coder();
+var Base94Coder = class extends DigitCoder {
+	charMap = "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~";
+};
+const BASE94_CODER = new Base94Coder();
+// src/protocol.ts
+var Protocol = class {
+	distribution;
+	coder;
+	constructor(distribution, coder) {
+		this.distribution = distribution;
+		this.coder = coder;
+	}
+	encode(data) {
+		return this.coder.encode(this.distribution.encode(data));
+	}
+	decode(code) {
+		return this.distribution.decode(this.coder.decode(code));
+	}
+};
+export { ArithmeticRange, ArithmeticValue, BASE64URL_CODER, BASE64_CODER, BASE94_CODER, Base64Coder, Base64UrlCoder, Base94Coder, DigitCoder, Distribution, Fraction, Protocol, Serializer, StringCoder, Z85Coder, Z85_CODER, frac };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "arithcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Arithmetic coding + String coder",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist"],
+  "exports": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "bugs": {
+    "url": "https://github.com/idiotf/arithcode/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/idiotf/arithcode.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10",
+    "@types/node": "^20",
+    "@types/seedrandom": "^3.0.8",
+    "eslint": "^10",
+    "globals": "^17.6.0",
+    "jiti": "^2.7.0",
+    "prettier": "^3.8.3",
+    "publint": "^0.3.25",
+    "seedrandom": "^3.0.5",
+    "tsdown": "^0.23.4",
+    "typescript": "^6",
+    "typescript-eslint": "^8.72.1"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "format": "prettier -w '**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown --publint",
+    "prepack": "bun run build"
+  }
+}