@ducatjs/money 0.1.0 → 0.2.1

package/src/valibot.ts

@@ -0,0 +1,87 @@
+/**
+ * `@ducatjs/money/valibot`: Valibot schemas for the JSON form of Money, `{ "amount": "12.34",
+ * "currency": "EUR" }`, for API boundaries. Valibot is an optional peer dependency: only this entry
+ * imports it.
+ */
+import * as valibot from 'valibot';
+import { isMoney, type Money, type MoneyJSON } from './money.js';
+import {
+  checkSchemaOptions,
+  readMoneyJSON,
+  type MoneyFor,
+  type MoneyIssue,
+  type MoneySchemaOptions,
+} from './schema.js';
+
+export type { MoneyFor, MoneySchemaOptions } from './schema.js';
+
+const jsonShape = valibot.object({ amount: valibot.string(), currency: valibot.string() });
+
+/** The schema type both functions return: the JSON shape, then a transformation. */
+export type MoneySchema<TOutput> = valibot.SchemaWithPipe<
+  readonly [typeof jsonShape, valibot.RawTransformAction<MoneyJSON, TOutput>]
+>;
+
+/** A Valibot issue path pointing at the field that is wrong. */
+function pathTo(json: MoneyJSON, issue: MoneyIssue): [valibot.ObjectPathItem] {
+  return [
+    {
+      type: 'object',
+      origin: 'value',
+      input: json as unknown as Record<string, unknown>,
+      key: issue.field,
+      value: json[issue.field],
+    },
+  ];
+}
+
+/**
+ * Parses `{ amount, currency }` into Money, accepting exactly what the Zod entry accepts (see its
+ * `moneySchema`): an exact decimal string with no more decimals than the scale and at most
+ * `maxDigits` digits, padded to the scale, and a listed or known currency. Problems are Valibot
+ * issues on `amount` or `currency`; other keys are dropped. Bad options throw when the schema is
+ * built. Valibot has no codecs, so encode with `money.toJSON()` (or `JSON.stringify`), which this
+ * schema reads back.
+ *
+ *     const Order = valibot.object({ total: moneySchema({ currency: 'EUR' }) })
+ *     v.parse(Order, { total: { amount: '12.34', currency: 'EUR' } }).total   // Money<'EUR'>
+ */
+export function moneySchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneySchema<MoneyFor<C>> {
+  checkSchemaOptions(options);
+  return valibot.pipe(
+    jsonShape,
+    valibot.rawTransform<MoneyJSON, MoneyFor<C>>(({ dataset, addIssue, NEVER }) => {
+      const json = dataset.value;
+      const result = readMoneyJSON(json, options);
+      if (isMoney(result)) {
+        return result as Money as MoneyFor<C>;
+      }
+      addIssue({ message: result.message, path: pathTo(json, result) });
+      return NEVER;
+    }),
+  );
+}
+
+/**
+ * Like `moneySchema`, but the output stays the JSON object: it checks that the input would parse,
+ * for code that passes the JSON on rather than computing with it.
+ */
+export function moneyJSONSchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneySchema<MoneyJSON<C>> {
+  checkSchemaOptions(options);
+  return valibot.pipe(
+    jsonShape,
+    valibot.rawTransform<MoneyJSON, MoneyJSON<C>>(({ dataset, addIssue, NEVER }) => {
+      const json = dataset.value;
+      const result = readMoneyJSON(json, options);
+      if (isMoney(result)) {
+        return json as MoneyJSON<C>;
+      }
+      addIssue({ message: result.message, path: pathTo(json, result) });
+      return NEVER;
+    }),
+  );
+}

package/src/zod.ts

@@ -0,0 +1,78 @@
+/**
+ * `@ducatjs/money/zod`: Zod schemas for the JSON form of Money, `{ "amount": "12.34", "currency":
+ * "EUR" }`, for API boundaries. Zod is an optional peer dependency: only this entry imports it.
+ */
+import { z } from 'zod';
+import { isMoney, type Money, type MoneyJSON } from './money.js';
+import {
+  checkSchemaOptions,
+  readMoneyJSON,
+  type MoneyFor,
+  type MoneySchemaOptions,
+} from './schema.js';
+
+export type { MoneyFor, MoneySchemaOptions } from './schema.js';
+
+const jsonShape = z.object({ amount: z.string(), currency: z.string() });
+
+/** The schema `moneySchema` returns: a Zod codec between the JSON form and Money. */
+export type MoneyCodec<C extends string> = z.ZodCodec<typeof jsonShape, z.ZodCustom<MoneyFor<C>>>;
+
+/**
+ * Parses `{ amount, currency }` into Money, and encodes Money back to that JSON form. It is a Zod
+ * codec, so `schema.parse(json)` (or `z.decode`) gives Money and `z.encode(schema, money)` gives
+ * `{ amount, currency }`, written at the amount's own scale.
+ *
+ * The amount must be an exact decimal string with no more decimals than the scale (the
+ * currency's exponent unless `scale` is given; `rounding` allows more), and at most `maxDigits`
+ * digits. The currency must be one of `currency`, or any known code. Shorter amounts are padded to
+ * the scale ("1.5" EUR gives 1.50 EUR). Problems are Zod issues on `amount` or `currency`; keys
+ * other than those two are dropped. Bad options throw when the schema is built.
+ *
+ *     const Order = z.object({ total: moneySchema({ currency: 'EUR' }) })
+ *     Order.parse({ total: { amount: '12.34', currency: 'EUR' } }).total   // Money<'EUR'>
+ */
+export function moneySchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): MoneyCodec<C> {
+  checkSchemaOptions(options);
+  return z.codec(
+    jsonShape,
+    z.custom<MoneyFor<C>>((value) => isMoney(value)),
+    {
+      decode: (json, payload) => {
+        const result = readMoneyJSON(json, options);
+        if (isMoney(result)) {
+          return result as Money as MoneyFor<C>;
+        }
+        payload.issues.push({
+          code: 'custom',
+          message: result.message,
+          input: json,
+          path: [result.field],
+        });
+        return z.NEVER;
+      },
+      encode: (value) => (value as Money).toJSON(),
+    },
+  );
+}
+
+/**
+ * Like `moneySchema`, but the output stays the JSON object (with only `amount` and `currency`): it
+ * checks that the input would parse, for code that passes the JSON on rather than computing with
+ * it.
+ */
+export function moneyJSONSchema<C extends string = string>(
+  options?: MoneySchemaOptions<C>,
+): z.ZodType<MoneyJSON<C>, MoneyJSON> {
+  checkSchemaOptions(options);
+  return jsonShape.transform((json, context) => {
+    const result = readMoneyJSON(json, options);
+    if (isMoney(result)) {
+      return json as MoneyJSON<C>;
+    }
+    context.addIssue({ code: 'custom', message: result.message, path: [result.field] });
+    return z.NEVER;
+  });
+}