@amboras-dev/money 0.0.0-stage → 0.2.0

package/dist/sql.js

@@ -0,0 +1,271 @@
+import { $ as describeValue, A as storageScale, E as resolveCurrency, Q as MoneyError, u as CURRENCIES } from "./money-WhnGiI00.js";
+import { r as checkRate } from "./rate-DicStBue.js";
+import { t as priceRoundingParams } from "./retail-1mu888J1.js";
+//#region src/sql/guard.ts
+const STATEMENT_BREAKERS = /;|--|\/\*|\*\/|\0/;
+const refuse = (name, value) => new MoneyError("parse", `${name} must be a SQL expression written in code, got ${describeValue(value)}`);
+/** Code-written text, or `parse` when it is blank, could break out of the expression or holds a `?` placeholder. */
+function fragment(value, name) {
+	if (typeof value !== "string" || value.trim() === "" || STATEMENT_BREAKERS.test(value) || value.includes("?")) throw refuse(name, value);
+	return value;
+}
+const isFragment = (value) => typeof value === "object" && value !== null && typeof value.sql === "string";
+/**
+* An expression argument as a SqlFragment: code-written text through `fragment`, or a fragment
+* whose text could not break out and holds exactly one `?` per binding.
+*/
+function expression(value, name) {
+	if (!isFragment(value)) return {
+		sql: fragment(value, name),
+		bindings: []
+	};
+	const { sql: text, bindings } = value;
+	const placeholders = text.split("?").length - 1;
+	if (text.trim() === "" || STATEMENT_BREAKERS.test(text) || !Array.isArray(bindings) || bindings.length !== placeholders) throw refuse(name, text);
+	return value;
+}
+/** One placeholder bound to `value`. */
+const bind = (value) => ({
+	sql: "?",
+	bindings: [value]
+});
+/** SQL text the package writes itself (keywords, registry code lists, digits): no bindings. */
+const raw = (text) => ({
+	sql: String(text),
+	bindings: []
+});
+/** Template text joined with fragments, their bindings concatenated in the order they appear. */
+function sql(strings, ...parts) {
+	let text = strings[0];
+	const bindings = [];
+	parts.forEach((part, i) => {
+		text += part.sql + strings[i + 1];
+		bindings.push(...part.bindings);
+	});
+	return {
+		sql: text,
+		bindings
+	};
+}
+/** A JSON key or event name a builder binds, held to `/^[a-z][a-z0-9_]*$/`. */
+function token(value, name) {
+	if (typeof value !== "string" || !/^[a-z][a-z0-9_]*$/.test(value)) throw new MoneyError("parse", `${name} must match /^[a-z][a-z0-9_]*$/, got ${describeValue(value)}`);
+	return value;
+}
+function dialectOf(value) {
+	if (value !== "pg" && value !== "clickhouse") throw new MoneyError("parse", `Unknown SQL dialect: ${describeValue(value)}`);
+	return value;
+}
+//#endregion
+//#region src/sql/lists.ts
+const quoted = (pick) => CURRENCIES.filter(pick).map((info) => `'${info.code}'`).join(",");
+/** Storage scale 1000: `'BHD','IQD','JOD','KWD','LYD','OMR','TND'`. */
+const SCALE_1000_CODES = quoted((info) => info.storageScale === 1e3);
+/** Display digits 0 (ISO). */
+const DISPLAY_0_CODES = quoted((info) => info.displayDigits === 0);
+/** Display digits 3 (ISO). */
+const DISPLAY_3_CODES = quoted((info) => info.displayDigits === 3);
+/** Medusa core `decimal_digits` 0 (payment-status epsilon 1). */
+const MEDUSA_0_CODES = quoted((info) => info.medusaDigits === 0);
+/** Medusa core `decimal_digits` 3 (payment-status epsilon 0.001). */
+const MEDUSA_3_CODES = quoted((info) => info.medusaDigits === 3);
+//#endregion
+//#region src/sql/amounts.ts
+const CH_STORED_SCALE = 3;
+const CH_ROUND_SCALE = 12;
+/** The storage divisor of the currency in `codeExpr`, keyed by code (never `currency.decimal_digits`). */
+function storageDivisorSql(codeExpr, dialect = "pg") {
+	const code = expression(codeExpr, "codeExpr");
+	const codes = raw(SCALE_1000_CODES);
+	return dialectOf(dialect) === "pg" ? sql`(CASE WHEN upper(${code}) IN (${codes}) THEN 1000 ELSE 100 END)` : sql`if(upper(${code}) IN (${codes}), 1000, 100)`;
+}
+/**
+* A stored amount as major units, exactly: Postgres numeric division, ClickHouse
+* `toDecimal128(amount, 3)` over the divisor (a Decimal(38, 3), never a Float64).
+*/
+function storedToMajorSql(amountExpr, codeExpr, dialect = "pg") {
+	const amount = expression(amountExpr, "amountExpr");
+	const divisor = storageDivisorSql(codeExpr, dialect);
+	return dialect === "pg" ? sql`((${amount})::numeric / ${divisor})` : sql`(toDecimal128(${amount}, ${raw(CH_STORED_SCALE)}) / ${divisor})`;
+}
+/**
+* A major value rounded to the display digits of a constant currency or of the currency in a
+* column, half away from zero (D1) in both dialects: Postgres `ROUND(numeric)`, ClickHouse
+* `round()` on `toDecimal128(value, 12)` (a Float64 would round half-to-even).
+*/
+function roundMajorSql(expr, currency, dialect = "pg") {
+	const value = expression(expr, "expr");
+	const pg = dialectOf(dialect) === "pg";
+	const exact = pg ? sql`(${value})::numeric` : sql`toDecimal128(${value}, ${raw(CH_ROUND_SCALE)})`;
+	let digits;
+	if (typeof currency === "string") digits = raw(resolveCurrency(currency, { allowHistoric: true }).displayDigits);
+	else {
+		const code = expression(currency?.codeExpr, "codeExpr");
+		const zero = raw(DISPLAY_0_CODES);
+		const three = raw(DISPLAY_3_CODES);
+		digits = pg ? sql`(CASE WHEN upper(${code}) IN (${zero}) THEN 0 WHEN upper(${code}) IN (${three}) THEN 3 ELSE 2 END)` : sql`multiIf(upper(${code}) IN (${zero}), 0, upper(${code}) IN (${three}), 3, 2)`;
+	}
+	return pg ? sql`ROUND(${exact}, ${digits})` : sql`round(${exact}, ${digits})`;
+}
+/** Medusa core's payment-status epsilon for the currency in `codeExpr` (the `medusaEpsilon` table): 1, 0.001 or 0.01. */
+function medusaEpsilonSql(codeExpr) {
+	const code = expression(codeExpr, "codeExpr");
+	return sql`(CASE WHEN upper(${code}) IN (${raw(MEDUSA_0_CODES)}) THEN 1 WHEN upper(${code}) IN (${raw(MEDUSA_3_CODES)}) THEN 0.001 ELSE 0.01 END)`;
+}
+/** `a - b` within Medusa's epsilon for the currency (captured / refunded tolerance). */
+function withinEpsilonSql(aExpr, bExpr, codeExpr) {
+	return sql`((${expression(aExpr, "aExpr")}) - (${expression(bExpr, "bExpr")}) <= ${medusaEpsilonSql(codeExpr)})`;
+}
+/**
+* Decimal text as numeric, NULL when it is not plain decimal (`signed` default true allows a leading `-`).
+* The pattern spells optional parts as `{0,1}`: a literal `?` would read as a knex placeholder.
+*/
+function parseDecimalSql(expr, options = {}) {
+	const value = expression(expr, "expr");
+	return sql`(CASE WHEN (${value}) ~ '${raw(options.signed === false ? "^[0-9]+(\\.[0-9]+){0,1}$" : "^-{0,1}[0-9]+(\\.[0-9]+){0,1}$")}' THEN (${value})::numeric END)`;
+}
+/**
+* A Medusa summary total from a `totals` jsonb: `raw_<key>.value` first (exact), then `<key>`,
+* as `readStoredField` reads it; `''` is NULL. `nullAs: 0` (default) turns a missing total
+* into 0, `nullAs: null` keeps NULL. `key` must match `/^[a-z][a-z0-9_]*$/` (else `parse`); both
+* JSON keys are bindings.
+*/
+function summaryAmountSql(totalsExpr, key, options = {}) {
+	const totals = expression(totalsExpr, "totalsExpr");
+	const k = token(key, "key");
+	const value = sql`NULLIF(COALESCE(${totals} -> ${bind(`raw_${k}`)}::text ->> 'value', ${totals} ->> ${bind(k)}::text), '')::numeric`;
+	return options.nullAs === null ? value : sql`COALESCE(${value}, 0)`;
+}
+/** Medusa's raw BigNumber column for a stored amount expression. */
+function rawAmountJsonSql(expr) {
+	return sql`jsonb_build_object('value', (${expression(expr, "expr")})::text, 'precision', 20)`;
+}
+/** A currency code column normalised the way Medusa stores it. */
+function normalizeCurrencySql(expr) {
+	return sql`lower(btrim(${expression(expr, "expr")}))`;
+}
+//#endregion
+//#region src/sql/clickhouse.ts
+/**
+* The SELECT list and GROUP BY of per-currency purchase revenue in stored units. The event name
+* is a ClickHouse query parameter (`{revenue_event:String}`, pass `params` as `query_params`),
+* never inlined. GROUP BY names the `currency` alias: ClickHouse resolves aliases first, so
+* `GROUP BY lower(currency)` over an unqualified `currency` column fails with NOT_AN_AGGREGATE
+* (verified on 24.8).
+*/
+function chEventRevenueByCurrencySql(cols = {}) {
+	const value = fragment(cols.value ?? "value", "value");
+	const currency = fragment(cols.currency ?? "currency", "currency");
+	const eventType = fragment(cols.eventType ?? "event_type", "eventType");
+	const event = token(cols.event ?? "purchase", "event");
+	return {
+		select: `lower(${currency}) AS currency, sumIf(${value}, ${eventType} = {revenue_event:String}) AS revenue_stored`,
+		groupBy: "currency",
+		params: { revenue_event: event }
+	};
+}
+//#endregion
+//#region src/sql/ddl.ts
+/** The column type of a stored amount. */
+const STORAGE_AMOUNT_SQL_TYPE = "BIGINT";
+/** A column for DDL, which Postgres never parameterises: a fragment with bindings is `parse`. */
+function ddlColumn(column) {
+	const col = expression(column, "column");
+	if (col.bindings.length > 0) throw new MoneyError("parse", `DDL takes no bindings, got ${col.bindings.length} for ${col.sql}`);
+	return col;
+}
+/** Lower-case three-letter currency codes only. */
+function currencyCodeCheckSql(column) {
+	const col = ddlColumn(column);
+	return sql`CHECK (${col} = lower(${col}) AND char_length(${col}) = 3)`;
+}
+/**
+* The CHECK constraint of a stored-amount column: a finite (and, by default, non-negative)
+* amount or NULL.
+* - `'bigint'` (default): a BIGINT is always finite, so only the sign is checked:
+*   `CHECK (<col> IS NULL OR <col> >= 0)`. With `nonNegative: false` nothing is left to
+*   check and the result is `CHECK (true)`, so callers can still splice it unconditionally.
+*   Comparing a BIGINT with `'NaN'` would fail with `invalid input syntax for type bigint`.
+* - `'numeric'`: migration 106's form with both special-value halves compared as text
+*   (`<col>::text <> 'NaN' AND <col>::text <> 'Infinity' AND <col> >= 0`). NaN sorts above
+*   every number, so the sign clause alone would let it through. With `nonNegative: false`
+*   `'-Infinity'` is refused too, so the amount stays finite.
+*/
+function storageAmountCheckSql(column, options = {}) {
+	const col = ddlColumn(column);
+	const nonNegative = options.nonNegative !== false;
+	const columnType = options.columnType ?? "bigint";
+	if (columnType !== "bigint" && columnType !== "numeric") throw new MoneyError("amount_invalid", `columnType must be 'bigint' or 'numeric', got ${describeValue(columnType)}`);
+	if (columnType === "bigint") return nonNegative ? sql`CHECK (${col} IS NULL OR ${col} >= 0)` : sql`CHECK (true)`;
+	return sql`CHECK (${col} IS NULL OR (${col}::text <> 'NaN' AND ${col}::text <> 'Infinity' AND ${nonNegative ? sql`${col} >= 0` : sql`${col}::text <> '-Infinity'`}))`;
+}
+/** USD to credits, `ceil(usd x 100)` (D14), the twin of `billing.usdToCredits`. */
+function usdToCreditsSql(expr) {
+	return sql`CEIL((${expression(expr, "expr")})::numeric * ${raw(storageScale("USD"))})::int`;
+}
+/** A yearly price as its monthly equivalent, half away from zero, the twin of `billing.monthlyEquivalent`. */
+function monthlyEquivalentSql(expr) {
+	return sql`ROUND((${expression(expr, "expr")})::numeric / 12)`;
+}
+//#endregion
+//#region src/sql/fx.ts
+function factorsJson(table) {
+	resolveCurrency(table?.base, { allowHistoric: true });
+	return JSON.stringify(table.factors);
+}
+/**
+* A stored amount in the currency of `codeExpr` converted with the bound factor table
+* (`fx.storeFactors`): `output: 'stored'` rounds half away from zero to a storage unit of the
+* base per row; `'major'` gives exact major units of the base. A missing factor is NULL
+* (dropped by SUM, flagged by `reportingCompleteSql`), never 1.
+*/
+function toReportingSql(amountExpr, codeExpr, table, options) {
+	const amount = expression(amountExpr, "amountExpr");
+	const code = expression(codeExpr, "codeExpr");
+	const factor = sql`(${bind(factorsJson(table))}::jsonb ->> lower(${code}))::numeric`;
+	if (options?.output === "major") return sql`((${amount})::numeric * ${factor} / ${raw(resolveCurrency(table.base, { allowHistoric: true }).storageScale)})`;
+	if (options?.output !== "stored") throw new MoneyError("parse", `output must be 'stored' or 'major', got ${describeValue(options?.output)}`);
+	return sql`round((${amount})::numeric * ${factor})`;
+}
+/** True when every row's currency has a factor (`bool_and`); domain filters stay at the call site. */
+function reportingCompleteSql(codeExpr, table) {
+	const code = expression(codeExpr, "codeExpr");
+	return sql`bool_and((${bind(factorsJson(table))}::jsonb ->> lower(${code})) IS NOT NULL)`;
+}
+/**
+* A stored amount converted by `factor` (from `fx.convertFactor`, scale ratio included; its
+* numerator and denominator are bindings) into `to`, rounded once to the currency unit (whole
+* units for zero-decimal), then `retail: 'nearest'` (the market charm) if asked.
+*/
+function convertStoredSql(amountExpr, factor, options) {
+	const amount = expression(amountExpr, "amountExpr");
+	const { numerator, denominator } = checkRate(factor);
+	const { unit, majorUnit, charm } = priceRoundingParams(options?.to);
+	const exact = sql`(${amount})::numeric * ${bind(String(numerator))}::numeric / ${bind(String(denominator))}::numeric`;
+	const x = unit === 1 ? sql`ROUND(${exact})` : sql`(ROUND(${exact} / ${raw(unit)}) * ${raw(unit)})`;
+	const retail = options.retail ?? "none";
+	if (retail === "none") return x;
+	if (retail !== "nearest") throw new MoneyError("amount_invalid", `SQL retail rounding must be 'none' or 'nearest', got ${describeValue(retail)}`);
+	if (charm === null) {
+		const step = raw(100 * majorUnit);
+		return sql`(CASE WHEN ${x} <= 0 THEN ${x} ELSE CEIL(${x} / ${step}) * ${step} END)`;
+	}
+	const major = raw(majorUnit);
+	const whole = sql`(FLOOR(${x} / ${major}) * ${major})`;
+	return sql`(CASE WHEN ${x} <= 0 THEN ${x} WHEN ${x} <= ${whole} + ${raw(charm)} THEN ${whole} + ${raw(charm)} ELSE ${whole} + ${raw(majorUnit + charm)} END)`;
+}
+/** `convertStoredSql` with the factor and rounding read from columns, so one statement converts many currencies. */
+function convertStoredByColumnsSql(amountExpr, cols) {
+	const amount = expression(amountExpr, "amountExpr");
+	const n = expression(cols?.numerator, "numerator");
+	const d = expression(cols.denominator, "denominator");
+	const unit = expression(cols.unit, "unit");
+	const major = expression(cols.majorUnit, "majorUnit");
+	const charm = expression(cols.charm, "charm");
+	const retail = expression(cols.retail, "retail");
+	const x = sql`(ROUND((${amount})::numeric * ${n} / ${d} / ${unit}) * ${unit})`;
+	const whole = sql`(FLOOR(${x} / ${major}) * ${major})`;
+	return sql`(CASE WHEN ${retail} = 'none' THEN ${x} WHEN ${x} <= 0 THEN ${x} WHEN ${charm} IS NULL THEN CEIL(${x} / (100 * ${major})) * (100 * ${major}) WHEN ${x} <= ${whole} + ${charm} THEN ${whole} + ${charm} ELSE ${whole} + ${major} + ${charm} END)`;
+}
+//#endregion
+export { STORAGE_AMOUNT_SQL_TYPE, chEventRevenueByCurrencySql, convertStoredByColumnsSql, convertStoredSql, currencyCodeCheckSql, medusaEpsilonSql, monthlyEquivalentSql, normalizeCurrencySql, parseDecimalSql, rawAmountJsonSql, reportingCompleteSql, roundMajorSql, storageAmountCheckSql, storageDivisorSql, storedToMajorSql, summaryAmountSql, toReportingSql, usdToCreditsSql, withinEpsilonSql };