@aginnovationaustralia/calculator-inputs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,38 @@
+Creative Commons Attribution 4.0 International License
+
+Copyright (c) 2024 Agricultural Innovation Australia
+
+This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+You are free to:
+
+    Share — copy and redistribute the material in any medium or format
+    for any purpose, even commercially.
+
+    The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+Under the following terms:
+
+    Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+    No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+Notices:
+
+    You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+
+    No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+Additional terms:
+
+    All users of the Code must acknowledge AIA as the source and maintainer of the EAP Calculator Engine code. All users of the Code must acknowledge that free access to the Code is supported by the Australian Government through funding from the Improving Consistency of On-Farm Emissions Estimates Program.
+
+    The acknowledgement must be displayed in documentation, digital interfaces, or product materials where attribution of technical components is ordinarily provided.
+
+    This includes the right to display the ‘Powered by EAP’ (https://www.aiaeap.com/branding) logo in any systems which directly or indirectly use the open-source code, in a way which is clearly visible to third-party clients/customers/users of those systems.
+
+    At a minimum, the acknowledgement must state:
+
+    “This product incorporates the EAP Calculator Engine open-source code developed and maintained by Agricultural Innovation Australia Ltd. Free access to AIA’s open-source code is supported by the Australian Government through funding from the Improving Consistency of On-Farm Emissions Estimates Program”
+
+    Users may not imply or state endorsement by AIA, unless explicit written consent from AIA has been granted. Users must not imply or state endorsement by the Australian Government.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @aginnovationaustralia/calculator-inputs
 
-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.
+Zod schemas that validate user supplied values and turn them into input containers from [`@aginnovationaustralia/calculator-units`](https://www.npmjs.com/package/@aginnovationaustralia/calculator-units), with clean OpenAPI output: common number constraints and named enums become shared components referenced by `$ref`.
+
+You decide the shape of your inputs: the options each input takes, what of them is recorded on its container and emitted to OpenAPI, and what fields sit beside a number's `value`.
+
+## Requirements
+
+- **ESM only.** The package is published as ES modules. It works with `import`, with bundlers, and with `require()` on Node 22.12 or later (Node's built-in support for requiring ES modules).
+- **Node 22.19 or later**, as declared in `engines`.
+- **TypeScript:** use `moduleResolution` `nodenext`, `node16` or `bundler`, which read the `exports` map. The older `node` (`node10`) setting can't resolve the subpath entry points. CommonJS projects importing the package from TypeScript need TypeScript 5.8 or later with `module: nodenext`.
+- **Jest:** Jest in CommonJS mode can only `require()` ES modules on Node 24.9 or later. On earlier versions, run Jest in ESM mode, transform the package, or use Vitest.
+
+## Peer dependencies
+
+`zod` (v4) and `@aginnovationaustralia/calculator-units` are peer dependencies, and your project must have exactly one copy of each:
+
+- zod keeps schema metadata (component ids, descriptions) in a registry inside the zod module. Tools such as `zod-openapi` only see metadata registered with their own copy of zod.
+- `calculator-units` recognises existing `ValueStore`s with `instanceof`.
+
+## Setting up
+
+```ts
+import {
+  createEnumRegistry,
+  createInputBuilders,
+} from '@aginnovationaustralia/calculator-inputs';
+import { defaultUnitSystem } from '@aginnovationaustralia/calculator-units/defaults';
+import { z } from 'zod';
+
+// Named enums, each emitted once as an OpenAPI component
+const { enumSchema } = createEnumRegistry({ Gas: ['CO2', 'CH4', 'N2O'] });
+
+// Record extra metadata on input containers
+declare module '@aginnovationaustralia/calculator-units' {
+  interface Metadata {
+    modules?: string[];
+    quality?: Quality;
+  }
+}
+
+export const inputs = createInputBuilders({
+  system: defaultUnitSystem,
+  enumSchema,
+  // Describes a number input's unit, e.g. 'kilograms'. Added to its description and as `x-units`.
+  displayUnit: (unitFactory, tweaker) => describe(unitFactory(1)),
+  // Your options: their type is inferred from this parameter, and required on every input
+  toMeta: (options: { modules: [string, ...string[]] }) => ({
+    modules: options.modules,
+  }),
+  toOpenApi: (options) => ({ 'x-modules': options.modules }),
+  // Fields beside `value` on number inputs, and what they record
+  numberFields: { quality: QualitySchema.optional().default({}) },
+  numberFieldsToMeta: ({ quality }) => ({ quality }),
+});
+```
+
+## Building schemas
+
+```ts
+const FuelSchema = z.strictObject({
+  dieselLitres: inputs.numberInput(
+    (v) => volume('Fuel', v),
+    { name: 'Diesel', description: 'Diesel used', modules: ['1.1'] },
+    isNonNegative,
+  ),
+  gas: inputs.enumInput(['CO2', 'CH4'], {
+    name: 'Gas',
+    description: 'The gas',
+    modules: ['1.1'],
+  }),
+  irrigated: inputs.booleanInputOptional({
+    name: 'Irrigated',
+    description: 'Whether irrigated',
+    modules: ['6.1'],
+  }),
+});
+
+FuelSchema.parse({
+  dieselLitres: { value: 1200, quality: { Temporal: '2' } },
+  gas: 'CO2',
+});
+// { dieselLitres: Container<Volume<'Fuel'>>, gas: Container<'CO2' | 'CH4'>, irrigated: undefined }
+```
+
+| Builder                                       | Accepts                                     | Returns                 |
+| --------------------------------------------- | ------------------------------------------- | ----------------------- |
+| `numberInput(unitFactory, options, tweaker?)` | `{ value, ...numberFields }`                | a container of the unit |
+| `enumInput(values, options)`                  | one of a registered list of strings         | a string container      |
+| `literalInput(value, options)`                | exactly one string (inline, not registered) | a string container      |
+| `booleanInput(options)`                       | a boolean                                   | a boolean container     |
+
+Each has an `…Optional` variant (except `literalInput`) that also accepts `undefined`. Every input takes `name`, `description` and an optional `method` (`'1'` to `'4'`) as well as your options. A number input for any method other than 1 also carries its value on the method 2 track. Inputs take the methods of the unit system you give: for fewer methods, narrow the system, e.g. `system: defaultUnitSystem.withMethods('1', '2')`, and inputs for any other method won't compile.
+
+## Number validation
+
+`isNonNegative`, `isPositive`, `isProportion` and `isPercentage` add validation to a number input. Constraints that match a registered number schema are emitted as a `$ref` to a shared component: `NumberInput`, `NonNegativeNumberInput`, `ProportionNumberInput`, `PercentageNumberInput`, `PositiveNumberInput` and `MinOneNumberInput` are built in. Register more with `registerNumberSchema(id, tweaker)`.
+
+## Enums
+
+`createEnumRegistry(namedEnums, { unregisteredHint? })` returns `enumSchema(values)`, which gives the shared schema for a registered list of values in any order. Unregistered values throw, which fails a build that generates OpenAPI specs; registering the same values under two names throws too.

package/dist/builders.d.ts

@@ -0,0 +1,81 @@
+import type { Container, Metadata, Method, NumberUnit, RuleSet, UnitSystem } from '@aginnovationaustralia/calculator-units';
+import { z } from 'zod';
+import type { EnumSchema } from './enums.js';
+import { NumberSchemaTweaker } from './numbers.js';
+/** Options every input takes. Consumers add their own with the `O` type parameter. */
+export type BaseInputOptions<M extends Method = Method> = {
+    /** The input's name, recorded on its container. */
+    name: string;
+    /** Describes the input in the API documentation. */
+    description: string;
+    /**
+     * Which calculation method the value is for, '1' to '4'. Defaults to method 1. Narrow it in your
+     * own options type if your domain has fewer methods.
+     */
+    method?: M;
+};
+export type InputOptions<O, M extends Method = Method> = BaseInputOptions<M> & O;
+type FieldsInput<F extends z.ZodRawShape> = [keyof F] extends [never] ? unknown : z.input<z.ZodObject<F>>;
+type FieldsOutput<F extends z.ZodRawShape> = [keyof F] extends [never] ? unknown : z.output<z.ZodObject<F>>;
+/** The wire form of a number input: `{ value }` plus the consumer's extra fields. */
+type NumberWireInput<F extends z.ZodRawShape> = {
+    value: number;
+} & FieldsInput<F>;
+type NumberWireOutput<F extends z.ZodRawShape> = {
+    value: number;
+} & FieldsOutput<F>;
+export type NumberWireSchema<F extends z.ZodRawShape> = z.ZodType<NumberWireOutput<F>, NumberWireInput<F>>;
+/** A number input schema: validates the wire form and returns an input container. */
+export type NumberInputSchema<U, RS extends RuleSet, F extends z.ZodRawShape, M extends Method = Method> = z.ZodPipe<NumberWireSchema<F>, z.ZodTransform<Container<U, RS, M>, NumberWireOutput<F>>>;
+export type NumberInputSchemaOptional<U, RS extends RuleSet, F extends z.ZodRawShape, M extends Method = Method> = z.ZodPipe<z.ZodOptional<NumberWireSchema<F>>, z.ZodTransform<Container<U, RS, M> | undefined, NumberWireOutput<F> | undefined>>;
+/** An enum (or literal) input schema. */
+export type EnumInputSchema<T extends string, RS extends RuleSet, M extends Method = Method> = z.ZodPipe<EnumSchema<T>, z.ZodTransform<Container<T, RS, M>, z.output<EnumSchema<T>>>>;
+export type EnumInputSchemaOptional<T extends string, RS extends RuleSet, M extends Method = Method> = z.ZodPipe<z.ZodOptional<EnumSchema<T>>, z.ZodTransform<Container<T, RS, M> | undefined, z.output<EnumSchema<T>> | undefined>>;
+export type BooleanInputSchema<RS extends RuleSet, M extends Method = Method> = z.ZodPipe<z.ZodBoolean, z.ZodTransform<Container<boolean, RS, M>, boolean>>;
+export type BooleanInputSchemaOptional<RS extends RuleSet, M extends Method = Method> = z.ZodPipe<z.ZodOptional<z.ZodBoolean>, z.ZodTransform<Container<boolean, RS, M> | undefined, boolean | undefined>>;
+export type InputBuilderConfig<RS extends RuleSet, O extends object, F extends z.ZodRawShape, M extends Method = Method> = {
+    /** The unit system the input containers belong to. */
+    system: UnitSystem<RS, M>;
+    /** Gives the shared schema for a list of enum values; see `createEnumRegistry`. */
+    enumSchema: <TEnum extends string>(values: readonly TEnum[]) => EnumSchema<TEnum>;
+    /**
+     * Describes the unit a number input is measured in, e.g. 'kilograms'. It is added to the input's
+     * description and as `x-units` on its schema. Called with a factory for the unit, the number
+     * validation if there is any, and the input's options. Use the options when the unit a value is
+     * supplied in can't be worked out from the unit it is stored as, e.g. a mass supplied in tonnes.
+     */
+    displayUnit: (unitFactory: (value: number) => NumberUnit, tweaker: NumberSchemaTweaker | undefined, options: InputOptions<O, M>) => string;
+    /** Metadata to record on every input's container, from the consumer's options. */
+    toMeta?: (options: O) => Metadata;
+    /** Extra OpenAPI fields for every input's schema, from the consumer's options. */
+    toOpenApi?: (options: O) => Record<string, unknown>;
+    /** Fields allowed beside `value` in a number input, e.g. a data quality rating. */
+    numberFields?: F;
+    /** Metadata to record on a number input's container, from its extra fields. */
+    numberFieldsToMeta?: (fields: z.output<z.ZodObject<F>>) => Metadata;
+};
+/**
+ * Builds zod schemas that validate user supplied values and turn them into input containers of a
+ * unit system:
+ *
+ * - `numberInput(unitFactory, options, tweaker?)` accepts `{ value, ...numberFields }`
+ * - `enumInput(values, options)` accepts one of a registered list of strings
+ * - `literalInput(value, options)` accepts exactly one string
+ * - `booleanInput(options)` accepts a boolean
+ *
+ * plus an `Optional` variant of each (except literals), which also accepts `undefined`.
+ *
+ * Each consumer chooses the options its inputs take (`O`, inferred from `toMeta`/`toOpenApi`), what
+ * of them is recorded as metadata or emitted to OpenAPI, and what fields sit beside a number's
+ * `value` (`F`, inferred from `numberFields`).
+ */
+export declare const createInputBuilders: <RS extends RuleSet, M extends Method, O extends object = object, F extends z.ZodRawShape = Record<never, never>>(config: InputBuilderConfig<RS, O, F, M>) => {
+    numberInput: <U extends NumberUnit>(unitFactory: (value: number) => U, options: InputOptions<O, M>, tweaker?: NumberSchemaTweaker) => NumberInputSchema<U, RS, F, M>;
+    numberInputOptional: <U extends NumberUnit>(unitFactory: (value: number) => U, options: InputOptions<O, M>, tweaker?: NumberSchemaTweaker) => NumberInputSchemaOptional<U, RS, F, M>;
+    enumInput: <TEnum extends string>(values: readonly TEnum[], options: InputOptions<O, M>) => EnumInputSchema<TEnum, RS, M>;
+    enumInputOptional: <TEnum extends string>(values: readonly TEnum[], options: InputOptions<O, M>) => EnumInputSchemaOptional<TEnum, RS, M>;
+    literalInput: <TValue extends string>(value: TValue, options: InputOptions<O, M>) => EnumInputSchema<TValue, RS, M>;
+    booleanInput: (options: InputOptions<O, M>) => BooleanInputSchema<RS, M>;
+    booleanInputOptional: (options: InputOptions<O, M>) => BooleanInputSchemaOptional<RS, M>;
+};
+export {};

package/dist/builders.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { resolveNumberSchema } from './numbers.js';
+import { mapOptional } from './optional.js';
+/**
+ * Builds zod schemas that validate user supplied values and turn them into input containers of a
+ * unit system:
+ *
+ * - `numberInput(unitFactory, options, tweaker?)` accepts `{ value, ...numberFields }`
+ * - `enumInput(values, options)` accepts one of a registered list of strings
+ * - `literalInput(value, options)` accepts exactly one string
+ * - `booleanInput(options)` accepts a boolean
+ *
+ * plus an `Optional` variant of each (except literals), which also accepts `undefined`.
+ *
+ * Each consumer chooses the options its inputs take (`O`, inferred from `toMeta`/`toOpenApi`), what
+ * of them is recorded as metadata or emitted to OpenAPI, and what fields sit beside a number's
+ * `value` (`F`, inferred from `numberFields`).
+ */
+export const createInputBuilders = (config) => {
+    const { system, enumSchema, displayUnit, toMeta = () => ({}), toOpenApi = () => ({}), numberFields = {}, numberFieldsToMeta = () => ({}), } = config;
+    /** The `description` and consumer tags shared by every input schema. */
+    const openapiTags = (description, options) => ({
+        description,
+        ...toOpenApi(options),
+    });
+    const numberWireSchema = (units, tweaker) => z
+        .strictObject({ value: resolveNumberSchema(tweaker), ...numberFields })
+        .meta({ 'x-units': units });
+    const toNumberContainer = (unitFactory, options) => (wire) => {
+        const { value, ...fields } = wire;
+        return system.input(unitFactory(value), {
+            ...toMeta(options),
+            ...numberFieldsToMeta(fields),
+            name: options.name,
+            method: options.method,
+        });
+    };
+    const toContainer = (options) => (value) => system.input(value, {
+        ...toMeta(options),
+        name: options.name,
+        method: options.method,
+    });
+    const withUnits = (description, units) => `${description} (${units})`;
+    /** Accepts `{ value, ...numberFields }` and returns an input container of the unit. */
+    const numberInput = (unitFactory, options, tweaker) => {
+        const units = displayUnit(unitFactory, tweaker, options);
+        return numberWireSchema(units, tweaker)
+            .transform(toNumberContainer(unitFactory, options))
+            .meta(openapiTags(withUnits(options.description, units), options));
+    };
+    /**
+     * Like `numberInput`, but also accepts `undefined`. The display unit is worked out without the
+     * number validation, which matches how the emissions calculators have always described these.
+     */
+    const numberInputOptional = (unitFactory, options, tweaker) => {
+        const units = displayUnit(unitFactory, undefined, options);
+        return numberWireSchema(units, tweaker)
+            .optional()
+            .transform(mapOptional(toNumberContainer(unitFactory, options)))
+            .meta(openapiTags(withUnits(options.description, units), options));
+    };
+    /** Accepts one of a registered list of strings. */
+    const enumInput = (values, options) => enumSchema(values)
+        .meta(openapiTags(options.description, options))
+        .transform(toContainer(options));
+    const enumInputOptional = (values, options) => enumSchema(values)
+        .optional()
+        .meta(openapiTags(options.description, options))
+        .transform(mapOptional(toContainer(options)));
+    /**
+     * Accepts exactly one string, typically to select a variant. It is emitted inline as a
+     * single-value enum, so it doesn't need to be registered.
+     */
+    const literalInput = (value, options) => z
+        .enum([value])
+        .meta(openapiTags(options.description, options))
+        .transform(toContainer(options));
+    const booleanInput = (options) => z
+        .boolean()
+        .meta(openapiTags(options.description, options))
+        .transform(toContainer(options));
+    const booleanInputOptional = (options) => z
+        .boolean()
+        .optional()
+        .meta(openapiTags(options.description, options))
+        .transform(mapOptional(toContainer(options)));
+    return {
+        numberInput,
+        numberInputOptional,
+        enumInput,
+        enumInputOptional,
+        literalInput,
+        booleanInput,
+        booleanInputOptional,
+    };
+};

package/dist/enums.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+declare const makeEnumSchema: <TEnum extends string>(values: readonly TEnum[]) => z.ZodEnum<{ [k_1 in TEnum]: k_1; } extends infer T ? { [k in keyof T]: T[k]; } : never>;
+export type EnumSchema<TEnum extends string> = ReturnType<typeof makeEnumSchema<TEnum>>;
+/**
+ * Gives an inline schema for any list of values, emitted in place rather than as a shared
+ * component. Pass it as `enumSchema` when you don't want to name your enums.
+ */
+export declare const inlineEnumSchema: <TEnum extends string>(values: readonly TEnum[]) => EnumSchema<TEnum>;
+export type EnumRegistryOptions = {
+    /** Appended to the error for unregistered values, e.g. where to register them. */
+    unregisteredHint?: string;
+};
+/**
+ * Registers named enums, so each is emitted once as an OpenAPI component (with its name as the id)
+ * and referenced everywhere it is used. API client generators then produce a named enum type
+ * instead of a plain string.
+ *
+ * Returns `enumSchema`, which gives the shared schema for a list of values. The values may be in any
+ * order but must exactly match a registered enum; anything else throws, which fails a build that
+ * generates OpenAPI specs.
+ */
+export declare const createEnumRegistry: (namedEnums: Record<string, readonly string[]>, { unregisteredHint }?: EnumRegistryOptions) => {
+    enumSchema: <TEnum extends string>(values: readonly TEnum[]) => EnumSchema<TEnum>;
+};
+export {};

package/dist/enums.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/** Identifies a list of enum values regardless of their order. */
+const valuesKey = (values) => JSON.stringify([...values].sort());
+const makeEnumSchema = (values) => z.enum(values);
+/**
+ * Gives an inline schema for any list of values, emitted in place rather than as a shared
+ * component. Pass it as `enumSchema` when you don't want to name your enums.
+ */
+export const inlineEnumSchema = (values) => makeEnumSchema(values);
+/**
+ * Registers named enums, so each is emitted once as an OpenAPI component (with its name as the id)
+ * and referenced everywhere it is used. API client generators then produce a named enum type
+ * instead of a plain string.
+ *
+ * Returns `enumSchema`, which gives the shared schema for a list of values. The values may be in any
+ * order but must exactly match a registered enum; anything else throws, which fails a build that
+ * generates OpenAPI specs.
+ */
+export const createEnumRegistry = (namedEnums, { unregisteredHint = 'Register them with a name.' } = {}) => {
+    const schemasByValues = new Map();
+    for (const [id, values] of Object.entries(namedEnums)) {
+        const key = valuesKey(values);
+        const existing = schemasByValues.get(key);
+        if (existing) {
+            throw new Error(`Enums ${existing.meta()?.id} and ${id} have the same values; register them once`);
+        }
+        schemasByValues.set(key, makeEnumSchema(values).meta({ id }));
+    }
+    const enumSchema = (values) => {
+        const schema = schemasByValues.get(valuesKey(values));
+        if (!schema) {
+            throw new Error(`Enum values ${JSON.stringify(values)} are not registered. ${unregisteredHint}`);
+        }
+        return schema;
+    };
+    return { enumSchema };
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './builders.js';
+export * from './enums.js';
+export * from './numbers.js';
+export * from './optional.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './builders.js';
+export * from './enums.js';
+export * from './numbers.js';
+export * from './optional.js';

package/dist/numbers.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+/** Adds validation to a number schema, e.g. `(schema) => schema.min(0)`. */
+export type NumberSchemaTweaker = (schema: z.ZodNumber) => z.ZodNumber;
+export declare const isNonNegative: NumberSchemaTweaker;
+export declare const isPositive: NumberSchemaTweaker;
+export declare const isProportion: NumberSchemaTweaker;
+export declare const isPercentage: NumberSchemaTweaker;
+type NumberSchema = z.ZodType<number, number>;
+/**
+ * Registers a stable number schema for a set of constraints. Any number input whose constraints
+ * match exactly uses it, and is emitted as a `$ref` to the component `id`.
+ */
+export declare const registerNumberSchema: (id: string, tweaker?: NumberSchemaTweaker) => void;
+/**
+ * The number schema for a set of constraints: the registered component if one matches, otherwise
+ * an inline schema with those constraints.
+ */
+export declare const resolveNumberSchema: (tweaker?: NumberSchemaTweaker) => NumberSchema;
+export {};

package/dist/numbers.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export const isNonNegative = (schema) => schema.min(0);
+export const isPositive = (schema) => schema.gt(0);
+export const isProportion = (schema) => schema.min(0).max(1);
+export const isPercentage = (schema) => schema.min(0).max(100);
+/** Fingerprint a number schema's JSON Schema constraints (ignoring $schema). */
+const numberConstraintKey = (schema) => {
+    const json = z.toJSONSchema(schema);
+    const { $schema: _schema, ...rest } = json;
+    return JSON.stringify(rest);
+};
+/**
+ * Stable, description-free number schemas, each with an OpenAPI component id, so the common
+ * constraints are emitted once and shared by `$ref`.
+ */
+const builtInNumberSchemas = [
+    ['NumberInput', undefined],
+    ['NonNegativeNumberInput', isNonNegative],
+    ['ProportionNumberInput', isProportion],
+    ['PercentageNumberInput', isPercentage],
+    ['PositiveNumberInput', isPositive],
+    ['MinOneNumberInput', (schema) => schema.min(1)],
+];
+const numberSchemasByConstraint = new Map();
+/**
+ * Registers a stable number schema for a set of constraints. Any number input whose constraints
+ * match exactly uses it, and is emitted as a `$ref` to the component `id`.
+ */
+export const registerNumberSchema = (id, tweaker) => {
+    const schema = tweaker ? tweaker(z.number()) : z.number();
+    numberSchemasByConstraint.set(numberConstraintKey(schema), schema.meta({ id }));
+};
+for (const [id, tweaker] of builtInNumberSchemas) {
+    registerNumberSchema(id, tweaker);
+}
+/**
+ * The number schema for a set of constraints: the registered component if one matches, otherwise
+ * an inline schema with those constraints.
+ */
+export const resolveNumberSchema = (tweaker) => {
+    const schema = tweaker ? tweaker(z.number()) : z.number();
+    return numberSchemasByConstraint.get(numberConstraintKey(schema)) ?? schema;
+};

package/dist/optional.d.ts

@@ -0,0 +1,2 @@
+/** Curried helper for Zod `.optional().transform(...)` so `undefined` is never passed to `fn`. */
+export declare const mapOptional: <T, U>(fn: (value: T) => U) => (value: T | undefined) => U | undefined;

package/dist/optional.js

@@ -0,0 +1,2 @@
+/** Curried helper for Zod `.optional().transform(...)` so `undefined` is never passed to `fn`. */
+export const mapOptional = (fn) => (value) => value === undefined ? undefined : fn(value);

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@aginnovationaustralia/calculator-inputs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Zod schemas that turn user supplied values into @aginnovationaustralia/calculator-units containers, with stable OpenAPI components",
+  "keywords": [
+    "units",
+    "zod",
+    "openapi",
+    "inputs",
+    "calculator"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && pnpm run check:package",
+    "check:package": "publint && attw --pack . --profile esm-only",
+    "prepublishOnly": "pnpm run check:package",
+    "clean": "rm -rf dist",
+    "check:types": "tsc --noEmit",
+    "lint": "eslint . && pnpm run check:types",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aginnovationaustralia/emissions-calculators.git",
+    "directory": "packages/calculator-inputs"
+  },
+  "homepage": "https://github.com/aginnovationaustralia/emissions-calculators/tree/main/packages/calculator-inputs#readme",
+  "bugs": {
+    "url": "https://github.com/aginnovationaustralia/emissions-calculators/issues"
+  },
+  "author": "Agricultural Innovation Australia",
+  "license": "CC-BY-4.0",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "devDependencies": {
+    "@aginnovationaustralia/calculator-units": "workspace:*",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.7",
+    "decimal.js-light": "^2.5.1",
+    "jest": "^30.5.2",
+    "publint": "^0.3.24",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.3",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "@aginnovationaustralia/calculator-units": "workspace:^",
+    "zod": "^4.6.7"
+  }
+}