@kikuchan/decimal 0.1.0-alpha.3 → 0.1.0-alpha.4

package/index.d.ts

@@ -0,0 +1,109 @@
+//#region src/index.d.ts
+declare const __brand: unique symbol;
+interface DecimalInstance {
+  readonly [__brand]: never;
+}
+type DecimalLike = number | string | bigint | DecimalInstance | {
+  coeff: bigint;
+  digits: bigint;
+};
+type RoundingMode = 'trunc' | 'floor' | 'ceil' | 'round';
+interface Decimal {
+  readonly [__brand]: never;
+  coeff: bigint;
+  digits: bigint;
+  clone(): Decimal;
+  round$(digits?: bigint | number, force?: boolean): this;
+  round(digits?: bigint | number, force?: boolean): Decimal;
+  floor$(digits?: bigint | number, force?: boolean): this;
+  floor(digits?: bigint | number, force?: boolean): Decimal;
+  ceil$(digits?: bigint | number, force?: boolean): this;
+  ceil(digits?: bigint | number, force?: boolean): Decimal;
+  trunc$(digits?: bigint | number, force?: boolean): this;
+  trunc(digits?: bigint | number, force?: boolean): Decimal;
+  rescale$(digits?: bigint | number, mode?: RoundingMode): this;
+  rescale(digits?: bigint | number, mode?: RoundingMode): Decimal;
+  roundBy$(step: DecimalLike, mode?: RoundingMode): this;
+  roundBy(step: DecimalLike, mode?: RoundingMode): Decimal;
+  floorBy$(step: DecimalLike): this;
+  floorBy(step: DecimalLike): Decimal;
+  ceilBy$(step: DecimalLike): this;
+  ceilBy(step: DecimalLike): Decimal;
+  truncBy$(step: DecimalLike): this;
+  truncBy(step: DecimalLike): Decimal;
+  split$(digits?: bigint | number, mode?: RoundingMode): [Decimal, Decimal];
+  split(digits?: bigint | number, mode?: RoundingMode): [Decimal, Decimal];
+  splitBy$(step: DecimalLike, mode?: RoundingMode): [Decimal, Decimal];
+  splitBy(step: DecimalLike, mode?: RoundingMode): [Decimal, Decimal];
+  neg$(flag?: boolean): this;
+  neg(flag?: boolean): Decimal;
+  abs$(): this;
+  abs(): Decimal;
+  sign$(): this;
+  sign(): Decimal;
+  isZero(): boolean;
+  isPositive(): boolean;
+  isNegative(): boolean;
+  add$(v: DecimalLike): this;
+  add(v: DecimalLike): Decimal;
+  sub$(v: DecimalLike): this;
+  sub(v: DecimalLike): Decimal;
+  mul$(v: DecimalLike, digits?: number | bigint | undefined): Decimal;
+  mul(v: DecimalLike, digits?: number | bigint | undefined): Decimal;
+  shift10$(exponent: bigint | number): this;
+  shift10(exponent: bigint | number): Decimal;
+  inverse$(digits?: bigint | number): this;
+  inverse(digits?: bigint | number): Decimal;
+  div$(v: DecimalLike, digits?: bigint | number, mode?: RoundingMode): this;
+  div(v: DecimalLike, digits?: bigint | number): Decimal;
+  mod$(v: DecimalLike): this;
+  mod(v: DecimalLike): Decimal;
+  modPositive$(v: DecimalLike): this;
+  modPositive(v: DecimalLike): Decimal;
+  clamp$(minValue: DecimalLike | undefined, maxValue: DecimalLike | undefined): this;
+  clamp(minValue: DecimalLike | undefined, maxValue: DecimalLike | undefined): Decimal;
+  cmp(v: DecimalLike): number;
+  eq(v: DecimalLike): boolean;
+  neq(v: DecimalLike): boolean;
+  lt(v: DecimalLike): boolean;
+  gt(v: DecimalLike): boolean;
+  le(v: DecimalLike): boolean;
+  ge(v: DecimalLike): boolean;
+  between(a: DecimalLike | undefined, b: DecimalLike | undefined): boolean;
+  isCloseTo(v: DecimalLike, tolerance: DecimalLike): boolean;
+  pow$(exponent: DecimalLike, digits?: bigint | number): this;
+  pow(exponent: DecimalLike, digits?: bigint | number): Decimal;
+  root$(degree: bigint | number, digits?: bigint | number): this;
+  root(degree: bigint | number, digits?: bigint | number): Decimal;
+  sqrt$(digits?: bigint | number): this;
+  sqrt(digits?: bigint | number): Decimal;
+  log$(base: DecimalLike, digits?: bigint | number): this;
+  log(base: DecimalLike, digits?: bigint | number): Decimal;
+  order(): bigint;
+  toString(): string;
+  toFixed(fractionDigits: bigint | number): string;
+  number(): number;
+  integer(): bigint;
+}
+declare function Decimal(v: null): null;
+declare function Decimal(v: undefined): undefined;
+declare function Decimal(v: DecimalLike): Decimal;
+declare function Decimal(v: DecimalLike | null): Decimal | null;
+declare function Decimal(v: DecimalLike | undefined): Decimal | undefined;
+declare function Decimal(v: DecimalLike | undefined | null): Decimal | undefined | null;
+declare namespace Decimal {
+  function isDecimal(v: unknown): v is Decimal;
+  function isDecimalLike(v: unknown): v is DecimalLike;
+  function pow10(n: bigint | number): Decimal;
+  function minmax(...values: (DecimalLike | null | undefined)[]): [Decimal | null, Decimal | null];
+  function min(...values: (DecimalLike | null | undefined)[]): Decimal | null;
+  function max(...values: (DecimalLike | null | undefined)[]): Decimal | null;
+}
+declare const isDecimal: typeof Decimal.isDecimal;
+declare const isDecimalLike: typeof Decimal.isDecimalLike;
+declare const pow10: typeof Decimal.pow10;
+declare const minmax: typeof Decimal.minmax;
+declare const min: typeof Decimal.min;
+declare const max: typeof Decimal.max;
+//#endregion
+export { Decimal, Decimal as default, DecimalInstance, DecimalLike, RoundingMode, isDecimal, isDecimalLike, max, min, minmax, pow10 };

package/index.js

@@ -0,0 +1 @@
+function e(e,t=`Digits must be an integer`){if(typeof e==`number`){if(!Number.isFinite(e)||!Number.isInteger(e))throw Error(t);return BigInt(e)}return e}function t(t){let n=e(t);return n<0n?0n:n}function n(e){let t=Number(e);return t<b.length?b[t]:5n**BigInt(e)}function r(e){let t=Number(e);return t<x.length?x[t]:10n**BigInt(e)}function i(e,t,n){let r=BigInt(t);if(r<=0n)return new g(1n);let i=new g(1n),a=e.clone();for(;r&1n&&i.mul$(a,n),r>>=1n,r!==0n;)a.mul$(a,n);return i}function a(e,t,n,r){if(t.isZero()||r<=0)return new g(1n);let{guardPrec:a,rootPrec:s}=f(n,r),c=o(t.coeff).toString().padStart(r,`0`),l=e.round(s),u=new g(1n);for(let e=0;e<r;e++){l=l.root(10n,s);let t=c.charCodeAt(e)-48;if(t<=0)continue;let n=i(l.clone(),t,a);u.mul$(n,a)}return u.round$(n)}function o(e){return e<0n?-e:e}function s(e){if(e===``)throw Error(`Invalid number`);let t=1n,n=e;if(n[0]===`-`?(t=-1n,n=n.slice(1)):n[0]===`+`&&(n=n.slice(1)),n===``)throw Error(`Invalid number`);let r=n.indexOf(`.`),i=n,a=``;r>=0&&(i=n.slice(0,r),a=n.slice(r+1)),i===``&&(i=`0`);let o=(i+a).replace(/^0+/,``),s=o===``?`0`:o;return{coeff:t*BigInt(s),digits:BigInt(a.length)}}function c(e){let t=e.search(/[eE]/);if(t===-1)return s(e);let n=e.slice(0,t),r=e.slice(t+1);if(r.trim()===``)throw Error(`Invalid number`);let{coeff:i,digits:a}=s(n);return{coeff:i,digits:a-BigInt(r)}}function l(e,t){let n=e.digits>t.digits?e.digits:t.digits,i=n-e.digits,a=n-t.digits;return{digits:n,aCoeff:e.coeff*r(i),bCoeff:t.coeff*r(a)}}function u(e){let t=Math.max(0,Number(e));return Math.min(2**53-1,t)}function d(e,t,n){let r=u(t),i=u(n),a=Math.max(r,i)+1,o=Math.max(a,1),s=e+o;for(;;){let t=Math.ceil(s*v)+o,n=Math.max(t*2,1),r=Math.max(a,Math.ceil(Math.log10(n))+1);if(r<=o){let e=s+o;return{guardPrec:o,fracPrec:s,bits:t,divPrec:e}}o=r,s=e+o}}function f(e,t){let n=Math.max(1,t),r=Math.max(6,Math.ceil(Math.log10(n*4))+2),i=e+BigInt(r);return{guardPrec:i,rootPrec:i+BigInt(Math.max(r,6))}}function p(e,t){let n=Math.max(1,t.toString().replace(`-`,``).length),r=Math.max(12,n+4);return{iterPrec:e+BigInt(r),stopShift:e+2n}}function m(e,t,n,r){let i=[],a=[],o=new g(t),s=1n,c=n+Math.max(r,1);for(;o.le(e);)i.push(o),a.push(s),o=o.mul(o),s*=2n;let l=new g(e),u=0n;for(let e=i.length-1;e>=0;e--){let t=i[e];l.ge(t)&&(l.div$(t,c),u+=a[e])}return{exponent:u,remainder:l}}function h(e,t,n,r){let i=n+Math.max(r,1);if(e.eq(y))return{exponent:0n,remainder:y.clone()};if(e.ge(y))return m(e,t,n,r);let a=m(y.div(e,i),t,n,r);return a.remainder.eq(y)?{exponent:-a.exponent,remainder:y.clone()}:{exponent:-a.exponent-1n,remainder:y.div(a.remainder,i).mul$(t)}}var g=class s{coeff;digits;constructor(e,t){if(typeof e==`number`){if(e!==e||e===1/0||e===-1/0)throw Error(`Invalid number`);({coeff:this.coeff,digits:this.digits}=c(e.toString()))}else if(typeof e==`string`){let t=e.trim();if(t===``)throw Error(`Invalid number`);({coeff:this.coeff,digits:this.digits}=c(t))}else if(typeof e==`bigint`)this.coeff=e,this.digits=t??0n;else if(typeof e==`object`&&e&&`coeff`in e&&typeof e.coeff==`bigint`&&`digits`in e&&typeof e.digits==`bigint`)this.coeff=e.coeff,this.digits=e.digits;else throw Error(`Invalid input type for Decimal`)}clone(){return new s({coeff:this.coeff,digits:this.digits})}#e(e,t=0n){return C(e)&&(t=e.digits,e=e.coeff),this.coeff=e,this.digits=t,this}#t(e,t,n){let i=this.coeff,a=e.coeff,s=e.digits+t-this.digits;s>=0n?i*=r(s):a*=r(-s);let c=i/a,l=i-c*a;if(l!==0n&&n!==`trunc`){let e=i>=0n;switch(n){case`floor`:e||(c-=1n);break;case`ceil`:e&&(c+=1n);break;case`round`:{let t=o(l),n=a<0n?-a:a;t*2n>=n&&(c+=e?1n:-1n);break}default:break}}return this.#e(c,t)}#n(t,n=`trunc`){let i=e(t);if(this.isZero())return this.digits=i,this;if(i===this.digits)return this;if(i>this.digits){let e=r(i-this.digits);return this.coeff*=e,this.digits=i,this}return this.#t(y,i,n)}#r(){if(this.coeff===0n)return this.digits=0n,this;if(this.digits<=0n)return this;for(;this.digits>0n&&this.coeff%10n==0n;)this.coeff/=10n,this.digits-=1n;return this}round$(t=0,n=!1){let r=e(t);return!n&&this.digits<=r?this:this.#n(r,`round`)}round(e=0,t=!1){return this.clone().round$(e,t)}roundBy$(e,t=`round`){let n=new s(e).abs();if(n.isZero())throw Error(`Cannot align to zero`);return this.div$(n,0n,t).mul$(n)}roundBy(e,t=`round`){return this.clone().roundBy$(e,t)}floor$(t=0,n=!1){let r=e(t);return!n&&this.digits<=r?this:this.#n(r,`floor`)}floor(e=0,t=!1){return this.clone().floor$(e,t)}floorBy$(e){return this.roundBy$(e,`floor`)}floorBy(e){return this.clone().floorBy$(e)}ceil$(t=0,n=!1){let r=e(t);return!n&&this.digits<=r?this:this.#n(r,`ceil`)}ceil(e=0,t=!1){return this.clone().ceil$(e,t)}ceilBy$(e){return this.roundBy$(e,`ceil`)}ceilBy(e){return this.clone().ceilBy$(e)}trunc$(t=0,n=!1){let r=e(t);return!n&&this.digits<=r?this:this.#n(r,`trunc`)}trunc(e=0,t=!1){return this.clone().trunc$(e,t)}rescale$(e,t=`trunc`){return e==null?this.#r():this.#n(e,t)}rescale(e,t=`trunc`){return this.clone().rescale$(e,t)}truncBy$(e){return this.roundBy$(e,`trunc`)}truncBy(e){return this.clone().truncBy$(e)}#i(e){let t=this.clone();return e(this),[this,t.sub$(this)]}split$(e,t=`floor`){return this.#i(n=>n.#n(e??0n,t))}split(e,t=`floor`){return this.clone().split$(e,t)}splitBy$(e,t=`floor`){return this.#i(n=>n.roundBy$(e,t))}splitBy(e,t=`floor`){return this.clone().splitBy$(e,t)}neg$(e){return e!==!1&&(this.coeff=-this.coeff),this}neg(e){return this.clone().neg$(e)}isZero(){return this.coeff===0n}isPositive(){return this.coeff>0n}isNegative(){return this.coeff<0n}add$(e){let t=S(e),{digits:n,aCoeff:r,bCoeff:i}=l(this,t);return this.coeff=r+i,this.digits=n,this}add(e){return this.clone().add$(e)}sub$(e){let t=S(e),{digits:n,aCoeff:r,bCoeff:i}=l(this,t);return this.coeff=r-i,this.digits=n,this}sub(e){return this.clone().sub$(e)}mul$(e,t){let n=S(e);return this.coeff*=n.coeff,this.digits+=n.digits,t!==void 0&&this.round$(t),this}mul(e,t){return this.clone().mul$(e,t)}shift10$(t){let n=e(t,`Shift amount must be an integer`);return n===0n||(this.digits-=n),this}shift10(e){return this.clone().shift10$(e)}inverse$(e=_){if(this.isZero())throw Error(`Division by zero`);let n=t(e),r=this.clone();return this.#e(1n).div$(r,n)}inverse(e=_){return this.clone().inverse$(e)}div$(e,n,r=`round`){let i=n===void 0,a=t(n??_),o=S(e);if(o.isZero())throw Error(`Division by zero`);return this.isZero()?this:(this.#t(o,a,r),i?this.#r():this)}div(e,t,n=`round`){return this.clone().div$(e,t,n)}abs$(){return this.isNegative()&&(this.coeff=-this.coeff),this}abs(){return this.clone().abs$()}mod$(e){let t=S(e);if(t.isZero())throw Error(`Division by zero`);let{digits:n,aCoeff:r,bCoeff:i}=l(this,t);return this.coeff=r%i,this.digits=n,this}mod(e){return this.clone().mod$(e)}modPositive$(e){let t=S(e);if(t.isNegative())throw Error(`Modulo divisor must be positive`);return this.mod$(t),this.isNegative()&&this.add$(t),this}modPositive(e){return this.clone().modPositive$(e)}clamp$(e,t){let n=S(e),r=S(t);if(n&&r&&n.gt(r))throw Error(`Invalid clamp range`);return n&&this.lt(n)?(this.coeff=n.coeff,this.digits=n.digits,this):r&&this.gt(r)?(this.coeff=r.coeff,this.digits=r.digits,this):this}clamp(e,t){return this.clone().clamp$(e,t)}cmp(e){let t=S(e),{aCoeff:n,bCoeff:r}=l(this,t);return n===r?0:n>r?1:-1}eq(e){return this.cmp(e)===0}neq(e){return this.cmp(e)!==0}lt(e){return this.cmp(e)<0}gt(e){return this.cmp(e)>0}le(e){return this.cmp(e)<=0}ge(e){return this.cmp(e)>=0}between(e,t){let n=S(e),r=S(t);if(n&&r&&n.gt(r))throw Error(`Invalid between range`);return!(n&&this.lt(n)||r&&this.gt(r))}isCloseTo(e,t){let n=S(t);if(n.isNegative())throw Error(`Tolerance must be non-negative`);return this.sub(e).abs$().le(n)}pow$(e,n=_){let r=t(n),o=S(e);if(o.isZero())return this.#e(1n);if(this.isZero()){if(o.isNegative())throw Error(`Zero to negative exponent is undefined`);return this}let s=o.isNegative(),[c,l]=o.abs().split$(),u=this.clone(),d=l.isZero()?0:Number(l.digits);if(u.isNegative()&&d>0)throw Error(`Fractional exponent requires non-negative base`);let f=i(u,c.coeff),p=r;d>0&&(p=r+BigInt(Math.max(4,d)));let m=a(u,l,p,d);d>0&&f.mul$(m,p);let h=p>r?p:r,g=d>0?p:r;return s?this.#e(1n).div$(f,h):(f.round$(h,!0),this.#e(f)),this.round$(g,g===0n),this}pow(e,t=_){return this.clone().pow$(e,t)}root$(n,r=_){let a=e(n,`Root degree must be an integer`);if(a<=0n)throw Error(`Invalid root degree`);let o=t(r);if(a===1n)return o<this.digits?this:this.trunc$(o,!0);if(this.isZero())return this;let c=this.isNegative();if(c&&a%2n==0n)throw Error(`Even root of negative value is not defined`);let l=this.abs(),u=a-1n,{iterPrec:d,stopShift:f}=p(o,a),m=T(-f),h=(()=>{let e=l.number();if(Number.isFinite(e)&&e>0){let t=Number(a);if(t>0){let n=e**(1/t);if(Number.isFinite(n)&&n>0)return new s(n).round$(d,!0)}}return new s(T(l.order()/a)).round$(d,!0)})();this.#e(h.coeff,h.digits),this.isZero()&&this.#e(1n);for(let e=0;e<64;e++){let e=i(this.clone(),u,d);if(e.isZero())break;let t=l.div(e,d),n=this.mul(u,d).add$(t).div$(a,d);if(n.isCloseTo(this,m)||n.eq(this)){this.#e(n);break}this.#e(n)}return this.round$(d,!0),this.round$(o,o===0n),c&&this.neg$(),this}root(e,t=_){return this.clone().root$(e,t)}sqrt$(e=_){return this.root$(2n,e)}sqrt(e=_){return this.clone().sqrt$(e)}log$(e,r=_){let i=Number(t(r)),a=new s(e);if(!this.isPositive())throw Error(`Logarithm argument must be positive`);if(!a.isPositive())throw Error(`Logarithm base must be positive`);if(a.eq(y))throw Error(`Logarithm base cannot be one`);let{guardPrec:o,fracPrec:c,bits:l,divPrec:u}=d(i,a.digits,this.digits),f=a.lt(y),p=f?y.div(a,u):a,{exponent:m,remainder:g}=h(this,p,c,o);if(this.#e(m),c>0){let e=0n;for(let t=0;t<l;t++)g.mul$(g,u),e<<=1n,g.ge(p)&&(g.div$(p,u),e|=1n);e!==0n&&this.add$({coeff:e*n(l),digits:BigInt(l)})}let v=i===0?0:c;return this.round$(v),f&&this.neg$(),this}log(e,t=_){return this.clone().log$(e,t)}sign$(){return this.isZero()?this:(this.coeff=this.coeff<0n?-1n:1n,this.digits=0n,this)}sign(){return this.clone().sign$()}order(){if(this.isZero())throw RangeError(`order undefined for 0`);return BigInt(o(this.coeff).toString().length)-1n-this.digits}toFixed(t){let n=`Fraction digits must be a non-negative integer`,r=e(t,n);if(r<0n)throw Error(n);return this.round(r,!0).toString()}toString(){if(this.coeff===0n)return this.digits<=0n?`0`:`0.${`0`.repeat(Number(this.digits))}`;let e=this.coeff<0n,t=e?`-`:``,n=(e?-this.coeff:this.coeff).toString();if(this.digits<=0n)return`${t}${n}${`0`.repeat(Number(-this.digits))}`;let r=Number(this.digits),i=n.padStart(r+1,`0`),a=i.length-r;return`${t}${i.slice(0,a)}.${i.slice(a).padEnd(r,`0`)}`}[Symbol.for(`nodejs.util.inspect.custom`)](e,t){return`colors`in t&&t?.colors?`\x1b[33m${this.toString()}\x1b[m \x1b[90m(${this.coeff} * 10 ** ${-this.digits})\x1b[m`:this.toString()}number(){return Number(this.toString())}integer(){return this.digits<=0n?this.coeff*r(-this.digits):this.coeff/r(this.digits)}};const _=18n,v=Math.log2(10),y=new g(1n),b=[],x=[];(function(){for(let e=0;e<256;e++)x[e]=10n**BigInt(e),b[e]=5n**BigInt(e)})();function S(e){return e==null||C(e)?e:new g(e)}(function(e){function t(e){return e instanceof g}e.isDecimal=t;function n(e){return!!(t(e)||typeof e==`string`||typeof e==`number`||typeof e==`bigint`||typeof e==`object`&&e&&`coeff`in e&&`digits`in e&&typeof e.coeff==`bigint`&&typeof e.digits==`bigint`)}e.isDecimalLike=n;function r(e){return new g({coeff:1n,digits:-BigInt(e)})}e.pow10=r;function i(...e){let t=null,n=null;for(let r=0;r<e.length;r++){let i=S(e[r]);i!=null&&((t===null||i.lt(t))&&(t=i),(n===null||i.gt(n))&&(n=i))}return[t,n]}e.minmax=i;function a(...e){return i(...e)[0]}e.min=a;function o(...e){return i(...e)[1]}e.max=o})(S||={});const C=S.isDecimal,w=S.isDecimalLike,T=S.pow10,E=S.minmax,D=S.min,O=S.max;var k=S;export{S as Decimal,k as default,C as isDecimal,w as isDecimalLike,O as max,D as min,E as minmax,T as pow10};

package/package.json

@@ -6,14 +6,20 @@
     "arbitrary",
     "bigint"
   ],
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./index.js",
   "author": "kikuchan <kikuchan98@gmail.com>",
   "homepage": "https://github.com/kikuchan/utils-on-npm#readme",
   "license": "MIT",
-  "scripts": {
-    "build": "tsdown",
-    "type:check": "tsc --noEmit"
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "repository": {
+    "url": "https://github.com/kikuchan/utils-on-npm"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 kikuchan
-
-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,219 +0,0 @@
-# @kikuchan/decimal
-
-Arbitrary precision decimal arithmetic for TypeScript and JavaScript. Avoids binary floating-point rounding errors.
-
-## Installation
-
-```bash
-npm install @kikuchan/decimal
-```
-
-## Quick Start
-
-```ts
-import { Decimal } from '@kikuchan/decimal';
-
-const price = Decimal('12.345');
-const quantity = Decimal(3);
-const total = price.mul(quantity).round(2);
-
-console.log(total.toString()); // "37.04"
-```
-
-## Creating Decimals
-
-The `Decimal()` constructor accepts numbers, strings, bigints, or existing Decimal instances:
-
-```ts
-Decimal(100)           // from number
-Decimal('12.345')      // from string
-Decimal('1.5e2')       // scientific notation
-Decimal(12345n)        // from bigint
-Decimal(existing)      // from another Decimal
-
-// Nullable values pass through unchanged
-Decimal(null)          // returns null
-Decimal(undefined)     // returns undefined
-```
-
-## API Overview
-
-### Arithmetic Operations
-
-All operations are **immutable by default** and return new Decimal instances:
-
-```ts
-const a = Decimal('10.5');
-const b = Decimal('2.3');
-
-a.add(b)        // addition
-a.sub(b)        // subtraction
-a.mul(b)        // multiplication
-a.div(b)        // division (default 18 decimal places)
-a.div(b, 5)     // division with custom precision
-
-a.mod(b)        // modulo (same sign rules as JavaScript %)
-a.modPositive(b)  // always non-negative remainder
-```
-
-### Mutable Operations
-
-Methods ending with `$` modify the value in place and return `this`:
-
-```ts
-const value = Decimal('1.2345');
-value.round$(2);  // value is now 1.23
-
-// Both styles support chaining
-value.add$(1).mul$(2).round$(0);
-Decimal('10').add(5).mul(2).round(0);  // 30
-```
-
-### Rounding & Precision
-
-```ts
-const num = Decimal('12.3456');
-
-num.round(2)     // 12.35 (half away from zero)
-num.floor(2)     // 12.34
-num.ceil(2)      // 12.35
-num.trunc(2)     // 12.34
-
-// Negative precision rounds to powers of 10
-Decimal('1234').round(-2)  // 1200 (nearest hundred)
-
-// Round to specific step sizes
-Decimal('12.7').roundBy('0.5')  // 13.0
-Decimal('47').roundBy(10)       // 50
-```
-
-**Precision control:**
-- Positive values: digits after decimal point
-- Zero: round to whole units
-- Negative values: powers of ten (e.g., `-2` = hundreds)
-
-### Sign & Absolute Value
-
-```ts
-const num = Decimal('-5.5');
-
-num.neg()         // 5.5
-num.abs()         // 5.5
-num.isNegative()  // true
-num.isPositive()  // false
-num.isZero()      // false
-```
-
-### Comparison
-
-```ts
-const a = Decimal('10');
-const b = Decimal('20');
-
-a.cmp(b)      // -1 (less), 0 (equal), or 1 (greater)
-a.eq(b)       // false
-a.lt(b)       // true
-a.le(b)       // true
-a.gt(b)       // false
-a.ge(b)       // false
-
-a.between(5, 15)        // true
-a.between(15, 25)       // false
-a.isCloseTo(10.001, 0.01)  // true
-```
-
-### Advanced Math
-
-```ts
-const num = Decimal('100');
-
-num.sqrt()           // square root
-num.root(3)          // cube root
-num.pow(2)           // exponentiation
-num.pow('0.5')       // fractional exponents (non-negative bases only)
-num.log(10)          // logarithm (base 10)
-num.inverse()        // 1 / num
-
-// All accept optional precision argument
-num.sqrt(10)         // 10 decimal places
-num.log(10, 20)      // 20 decimal places
-```
-
-### Decimal Point Manipulation
-
-```ts
-const num = Decimal('12.345');
-
-num.shift10(2)       // 1234.5 (shift right = multiply by 10²)
-num.shift10(-1)      // 1.2345 (shift left = divide by 10)
-
-// Split into integer and fractional parts
-const [whole, frac] = num.split(2);  // [12.34, 0.005]
-```
-
-### Conversion
-
-```ts
-const num = Decimal('12.345');
-
-num.toString()       // "12.345"
-num.toFixed(2)       // "12.35"
-num.number()         // 12.345 (native number)
-num.integer()        // 12n (bigint, truncated)
-```
-
-### Utilities
-
-```ts
-Decimal('12.3000').rescale()   // "12.3" (remove trailing zeros)
-
-const a = Decimal('5.5');
-a.clamp(0, 10)        // 5.5 (bounded)
-a.clamp(6, 10)        // 6 (clamped to minimum)
-
-// Exported utility functions
-import { min, max, minmax, pow10, isDecimal } from '@kikuchan/decimal';
-
-min(1, 2, 3)              // Decimal(1)
-max('1.5', '2.5', '3.5')  // Decimal(3.5)
-minmax(5, 1, 3)           // [Decimal(1), Decimal(5)]
-pow10(3)                  // Decimal(1000)
-isDecimal(value)          // type guard
-```
-
-## Rounding Modes
-
-All rounding operations support these modes:
-
-- `'round'` — half away from zero (default)
-- `'floor'` — toward negative infinity
-- `'ceil'` — toward positive infinity
-- `'trunc'` — toward zero
-
-```ts
-const num = Decimal('12.75');
-num.round(1, 'round')  // 12.8
-num.round(1, 'floor')  // 12.7
-num.round(1, 'ceil')   // 12.8
-num.round(1, 'trunc')  // 12.7
-```
-
-## Important Notes
-
-- **Immutability**: Operations return new instances unless using `$` methods
-- **Precision**: Division and advanced math default to 18 decimal places
-- **No silent overflow**: All operations maintain arbitrary precision
-- **Null-safe**: `Decimal(null)` and `Decimal(undefined)` pass through unchanged
-
-## Development
-
-```bash
-pnpm test      # Run tests
-pnpm build     # Build package
-pnpm lint      # Lint source
-pnpm format    # Check formatting
-```
-
-## License
-
-See LICENSE file for details.