iso-price 1.0.3

package/dist/domain.operations/precision/setPricePrecision.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPricePrecision = void 0;
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const IsoPriceRoundMode_1 = require("../../domain.objects/IsoPriceRoundMode");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+/**
+ * .what = extracts numeric exponent from exponent string
+ * .why = enables arithmetic on exponent values
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+/**
+ * .what = applies round mode to a bigint value
+ * .why = enables precision decrease with correct round behavior
+ */
+const applyRoundMode = (value, divisor, mode) => {
+    const quotient = value / divisor;
+    const remainder = value % divisor;
+    // no remainder = no need to round
+    if (remainder === 0n)
+        return quotient;
+    const isNegative = value < 0n;
+    const absRemainder = isNegative ? -remainder : remainder;
+    const halfDivisor = divisor / 2n;
+    switch (mode) {
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.FLOOR:
+            // always toward negative infinity
+            return isNegative ? quotient - 1n : quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.CEIL:
+            // always toward positive infinity
+            return isNegative ? quotient : quotient + 1n;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP:
+            // round half toward positive infinity
+            if (absRemainder >= halfDivisor) {
+                return isNegative ? quotient - 1n : quotient + 1n;
+            }
+            return quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_DOWN:
+            // round half toward zero
+            if (absRemainder > halfDivisor) {
+                return isNegative ? quotient - 1n : quotient + 1n;
+            }
+            return quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_EVEN:
+            // round half to nearest even (bankers round)
+            if (absRemainder > halfDivisor) {
+                return isNegative ? quotient - 1n : quotient + 1n;
+            }
+            if (absRemainder === halfDivisor) {
+                // round to even
+                const absQuotient = isNegative ? -quotient : quotient;
+                if (absQuotient % 2n !== 0n) {
+                    return isNegative ? quotient - 1n : quotient + 1n;
+                }
+            }
+            return quotient;
+        default:
+            return quotient;
+    }
+};
+/**
+ * .what = changes the precision of a price to a target exponent
+ * .why = enables precision increase (lossless) and decrease (with round)
+ *
+ * @example
+ * // increase precision (lossless)
+ * setPricePrecision({ of: 'USD 50.37', to: 'micro.x10^-6' })
+ * // => 'USD 50.370000'
+ *
+ * @example
+ * // decrease precision (requires round)
+ * setPricePrecision({ of: 'USD 5.555', to: 'centi.x10^-2' })
+ * // => 'USD 5.56' (default half-up)
+ *
+ * @example
+ * // decrease precision with explicit round mode
+ * setPricePrecision({ of: 'USD 5.555', to: 'centi.x10^-2' }, { round: 'floor' })
+ * // => 'USD 5.55'
+ */
+const setPricePrecision = (input, options) => {
+    // parse the input price
+    const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input.of);
+    // get current and target exponent values
+    const currentExp = getExponentValue(shape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    const targetExp = getExponentValue(input.to);
+    // calculate the scale difference
+    const scaleDiff = currentExp - targetExp;
+    let newAmount;
+    if (scaleDiff > 0) {
+        // precision increase — multiply (lossless)
+        const multiplier = 10n ** BigInt(scaleDiff);
+        newAmount = shape.amount * multiplier;
+    }
+    else if (scaleDiff < 0) {
+        // precision decrease — divide with round
+        const divisor = 10n ** BigInt(-scaleDiff);
+        const mode = options?.round ?? IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP;
+        newAmount = applyRoundMode(shape.amount, divisor, mode);
+    }
+    else {
+        // same precision
+        newAmount = shape.amount;
+    }
+    // build new shape with target exponent
+    const newShape = {
+        amount: newAmount,
+        currency: shape.currency,
+        exponent: input.to,
+    };
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(newShape);
+};
+exports.setPricePrecision = setPricePrecision;
+//# sourceMappingURL=setPricePrecision.js.map

package/dist/domain.operations/precision/setPricePrecision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setPricePrecision.js","sourceRoot":"","sources":["../../../src/domain.operations/precision/setPricePrecision.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/statistics/calcPriceAvg.d.ts

@@ -0,0 +1,21 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = calculates the average of an array of prices
+ * .why = enables statistical analysis of price data with precision safety
+ *
+ * @example
+ * calcPriceAvg(['USD 10.00', 'USD 20.00', 'USD 30.00'])
+ * // => 'USD 20.00'
+ *
+ * @example
+ * calcPriceAvg(['USD 10.00', 'USD 20.00'], { format: 'shape' })
+ * // => { amount: 1500n, currency: 'USD', exponent: 'centi.x10^-2' }
+ */
+export declare function calcPriceAvg<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options?: {
+    format?: 'words';
+}): IsoPriceWords<TCurrency>;
+export declare function calcPriceAvg<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options: {
+    format: 'shape';
+}): IsoPriceShape<TCurrency>;

package/dist/domain.operations/statistics/calcPriceAvg.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calcPriceAvg = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+function calcPriceAvg(prices, options) {
+    // validate input
+    if (prices.length === 0) {
+        throw new helpful_errors_1.BadRequestError('cannot calculate average of empty array', {
+            prices,
+        });
+    }
+    // convert all prices to shapes
+    const shapes = prices.map((p) => (0, asIsoPriceShape_1.asIsoPriceShape)(p));
+    // validate all currencies match
+    const currency = shapes[0].currency;
+    const mismatch = shapes.find((s) => s.currency !== currency);
+    if (mismatch) {
+        throw new helpful_errors_1.BadRequestError('cannot calculate average of mixed currencies', {
+            expected: currency,
+            found: mismatch.currency,
+        });
+    }
+    // find highest precision exponent (most negative = highest precision)
+    const exponents = shapes.map((s) => s.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    const targetExponent = findHighestPrecisionExponent(exponents);
+    // normalize all amounts to target exponent
+    const normalizedAmounts = shapes.map((s) => normalizeAmount(s.amount, s.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI, targetExponent));
+    // calculate sum
+    const sum = normalizedAmounts.reduce((acc, amt) => acc + amt, 0n);
+    // calculate average via bigint division (truncates toward zero)
+    const count = BigInt(prices.length);
+    const avgAmount = sum / count;
+    // build result shape
+    const resultShape = {
+        amount: avgAmount,
+        currency,
+        exponent: targetExponent,
+    };
+    if (options?.format === 'shape') {
+        return resultShape;
+    }
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+}
+exports.calcPriceAvg = calcPriceAvg;
+/**
+ * .what = finds the highest precision exponent from an array
+ * .why = ensures no precision loss when amounts are normalized
+ */
+const findHighestPrecisionExponent = (exponents) => {
+    let highestPrecision = exponents[0];
+    let highestValue = getExponentValue(highestPrecision);
+    for (const exp of exponents) {
+        const value = getExponentValue(exp);
+        if (value < highestValue) {
+            highestValue = value;
+            highestPrecision = exp;
+        }
+    }
+    return highestPrecision;
+};
+/**
+ * .what = extracts numeric exponent value from exponent string
+ * .why = enables comparison of exponent precision
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+/**
+ * .what = normalizes amount from source exponent to target exponent
+ * .why = enables arithmetic on amounts with different precisions
+ */
+const normalizeAmount = (amount, sourceExponent, targetExponent) => {
+    const sourceValue = getExponentValue(sourceExponent);
+    const targetValue = getExponentValue(targetExponent);
+    const diff = sourceValue - targetValue;
+    if (diff > 0) {
+        // source has lower precision, multiply to increase
+        return amount * 10n ** BigInt(diff);
+    }
+    if (diff < 0) {
+        // source has higher precision, divide to decrease (should not happen if target is highest)
+        return amount / 10n ** BigInt(-diff);
+    }
+    return amount;
+};
+//# sourceMappingURL=calcPriceAvg.js.map

package/dist/domain.operations/statistics/calcPriceAvg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calcPriceAvg.js","sourceRoot":"","sources":["../../../src/domain.operations/statistics/calcPriceAvg.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/statistics/calcPriceStdev.d.ts

@@ -0,0 +1,23 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = calculates the standard deviation of an array of prices
+ * .why = enables statistical analysis of price variance with precision safety
+ *
+ * uses population standard deviation formula: sqrt(sum((x - mean)^2) / n)
+ *
+ * @example
+ * calcPriceStdev(['USD 10.00', 'USD 20.00', 'USD 30.00'])
+ * // => 'USD 8.16' (approx)
+ *
+ * @example
+ * calcPriceStdev(['USD 10.00', 'USD 20.00'], { format: 'shape' })
+ * // => { amount: 500n, currency: 'USD', exponent: 'centi.x10^-2' }
+ */
+export declare function calcPriceStdev<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options?: {
+    format?: 'words';
+}): IsoPriceWords<TCurrency>;
+export declare function calcPriceStdev<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options: {
+    format: 'shape';
+}): IsoPriceShape<TCurrency>;

package/dist/domain.operations/statistics/calcPriceStdev.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calcPriceStdev = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+function calcPriceStdev(prices, options) {
+    // validate input
+    if (prices.length === 0) {
+        throw new helpful_errors_1.BadRequestError('cannot calculate stdev of empty array', {
+            prices,
+        });
+    }
+    // single value has zero variance
+    if (prices.length === 1) {
+        const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(prices[0]);
+        const resultShape = {
+            amount: 0n,
+            currency: shape.currency,
+            exponent: (shape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI),
+        };
+        if (options?.format === 'shape')
+            return resultShape;
+        return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+    }
+    // convert all prices to shapes
+    const shapes = prices.map((p) => (0, asIsoPriceShape_1.asIsoPriceShape)(p));
+    // validate all currencies match
+    const currency = shapes[0].currency;
+    const mismatch = shapes.find((s) => s.currency !== currency);
+    if (mismatch) {
+        throw new helpful_errors_1.BadRequestError('cannot calculate stdev of mixed currencies', {
+            expected: currency,
+            found: mismatch.currency,
+        });
+    }
+    // find highest precision exponent
+    const exponents = shapes.map((s) => s.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    const targetExponent = findHighestPrecisionExponent(exponents);
+    // normalize all amounts to target exponent
+    const normalizedAmounts = shapes.map((s) => normalizeAmount(s.amount, s.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI, targetExponent));
+    // calculate mean
+    const sum = normalizedAmounts.reduce((acc, amt) => acc + amt, 0n);
+    const count = BigInt(prices.length);
+    const mean = sum / count;
+    // calculate sum of squared deviations
+    // note: we use number for intermediate sqrt calculation, then convert back
+    let sumSquaredDev = 0n;
+    for (const amt of normalizedAmounts) {
+        const dev = amt - mean;
+        sumSquaredDev += dev * dev;
+    }
+    // calculate variance and stdev
+    // variance = sumSquaredDev / n (population stdev)
+    const variance = sumSquaredDev / count;
+    // sqrt via Newton's method for bigint (integer sqrt)
+    const stdevAmount = bigintSqrt(variance);
+    // build result shape
+    const resultShape = {
+        amount: stdevAmount,
+        currency,
+        exponent: targetExponent,
+    };
+    if (options?.format === 'shape') {
+        return resultShape;
+    }
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+}
+exports.calcPriceStdev = calcPriceStdev;
+/**
+ * .what = integer square root via Newton's method
+ * .why = enables sqrt calculation for bigint values
+ */
+const bigintSqrt = (n) => {
+    if (n < 0n) {
+        throw new helpful_errors_1.BadRequestError('cannot calculate sqrt of negative number', {
+            n,
+        });
+    }
+    if (n === 0n)
+        return 0n;
+    if (n === 1n)
+        return 1n;
+    // initial guess
+    let x = n;
+    let y = (x + 1n) / 2n;
+    // Newton's method iteration
+    while (y < x) {
+        x = y;
+        y = (x + n / x) / 2n;
+    }
+    return x;
+};
+/**
+ * .what = finds the highest precision exponent from an array
+ * .why = ensures no precision loss when amounts are normalized
+ */
+const findHighestPrecisionExponent = (exponents) => {
+    let highestPrecision = exponents[0];
+    let highestValue = getExponentValue(highestPrecision);
+    for (const exp of exponents) {
+        const value = getExponentValue(exp);
+        if (value < highestValue) {
+            highestValue = value;
+            highestPrecision = exp;
+        }
+    }
+    return highestPrecision;
+};
+/**
+ * .what = extracts numeric exponent value from exponent string
+ * .why = enables comparison of exponent precision
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+/**
+ * .what = normalizes amount from source exponent to target exponent
+ * .why = enables arithmetic on amounts with different precisions
+ */
+const normalizeAmount = (amount, sourceExponent, targetExponent) => {
+    const sourceValue = getExponentValue(sourceExponent);
+    const targetValue = getExponentValue(targetExponent);
+    const diff = sourceValue - targetValue;
+    if (diff > 0) {
+        return amount * 10n ** BigInt(diff);
+    }
+    if (diff < 0) {
+        return amount / 10n ** BigInt(-diff);
+    }
+    return amount;
+};
+//# sourceMappingURL=calcPriceStdev.js.map

package/dist/domain.operations/statistics/calcPriceStdev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calcPriceStdev.js","sourceRoot":"","sources":["../../../src/domain.operations/statistics/calcPriceStdev.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './contract/index';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contract/index"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC"}

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 ehmpathy
+
+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/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "iso-price",
+  "author": "ehmpathy",
+  "description": "type-safe price representation with sub-cent precision, iso 4217 currency support, and lossless arithmetic",
+  "version": "1.0.3",
+  "repository": "ehmpathy/iso-price",
+  "homepage": "https://github.com/ehmpathy/iso-price",
+  "keywords": [
+    "price",
+    "currency",
+    "money",
+    "iso-4217",
+    "bigint",
+    "precision",
+    "arithmetic",
+    "typescript"
+  ],
+  "bugs": "https://github.com/ehmpathy/iso-price/issues",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "dependencies": {
+    "domain-glossaries": "1.0.0",
+    "helpful-errors": "1.5.3"
+  },
+  "peerDependencies": {
+    "domain-objects": ">=0.24.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.8",
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
+    "@swc/core": "1.15.3",
+    "@swc/jest": "0.2.39",
+    "@tsconfig/node20": "20.1.5",
+    "@tsconfig/strictest": "2.0.5",
+    "@types/jest": "30.0.0",
+    "@types/node": "22.15.21",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "0.13.14",
+    "declapract-typescript-ehmpathy": "0.47.27",
+    "declastruct": "1.7.3",
+    "declastruct-github": "1.3.0",
+    "depcheck": "1.4.3",
+    "esbuild-register": "3.6.0",
+    "husky": "8.0.3",
+    "jest": "30.2.0",
+    "rhachet": "1.22.7",
+    "rhachet-roles-bhrain": "0.5.11",
+    "rhachet-roles-bhuild": "0.6.6",
+    "rhachet-roles-ehmpathy": "1.17.20",
+    "test-fns": "1.4.2",
+    "tsc-alias": "1.8.10",
+    "tsx": "4.20.6",
+    "typescript": "5.4.5",
+    "yalc": "1.0.0-pre.53"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:biome": "biome check --write",
+    "fix:format": "npm run fix:format:biome",
+    "fix:lint": "biome check --write",
+    "fix": "npm run fix:format && npm run fix:lint",
+    "build:clean:bun": "rm -f ./bin/*.bc",
+    "build:clean:tsc": "(chmod -R u+w dist 2>/dev/null || true) && rm -rf dist/",
+    "build:clean": "npm run build:clean:tsc && npm run build:clean:bun",
+    "build:compile:tsc": "tsc -p ./tsconfig.build.json && tsc-alias -p ./tsconfig.build.json",
+    "build:compile": "npm run build:compile:tsc && npm run build:compile:bun --if-present",
+    "build": "npm run build:clean && npm run build:compile && npm run build:complete --if-present",
+    "test:auth": "[ \"$ECHO\" = 'true' ] && echo '. .agent/repo=.this/role=any/skills/use.apikeys.sh' || . .agent/repo=.this/role=any/skills/use.apikeys.sh",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
+    "test:types": "tsc -p ./tsconfig.json --noEmit",
+    "test:format:biome": "biome format",
+    "test:format": "npm run test:format:biome",
+    "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
+    "test:lint:biome": "biome check --diagnostic-level=error",
+    "test:lint:biome:all": "biome check",
+    "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:integration": "jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main') $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "test": "eval $(ECHO=true npm run --silent test:auth) && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n $RESNAP ] && echo '--updateSnapshot')",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "prepare:husky": "husky install && chmod ug+x .husky/*",
+    "prepare:rhachet": "rhachet init --roles behaver mechanic reviewer"
+  }
+}