diff --git a/.changeset/numeric-32-bit-schemas.md b/.changeset/numeric-32-bit-schemas.md new file mode 100644 index 000000000..774e3c069 --- /dev/null +++ b/.changeset/numeric-32-bit-schemas.md @@ -0,0 +1,7 @@ +--- +"effect-app": minor +--- + +Add bounded 32-bit numeric schemas: `Int32`, `NonNegativeInt32`, `PositiveInt32` (signed Java `Integer` range, `format: "int32"`) and `NonNegativeNumber32`, `PositiveNumber32` (finite IEEE 754 binary32 range, `format: "float"`). Limits are enforced on decode and encode and emitted as JSON Schema / OpenAPI `minimum`/`maximum`. Float bounds are Java's `Float.MAX_VALUE` / `Float.MIN_VALUE` literals (`3.4028235E38`, `1.4E-45`), so every accepted value stays finite in binary32 and `PositiveNumber32` values stay non-zero (no overflow / underflow). Values are not rounded. Brands extend the existing `Int`/`NonNegativeInt`/`PositiveInt`/`NonNegativeNumber`/`PositiveNumber` brands. Bound constants `INT32_MIN`, `INT32_MAX`, `FLOAT32_MIN_POSITIVE`, `FLOAT32_MAX` are exported. + +`flattenSimpleAllOf` now intersects repeated bounds (tighter `minimum`/`maximum`/length bounds win) and keeps the `allOf` when other non-annotation keywords conflict, instead of letting the last `allOf` member overwrite parent constraints. diff --git a/packages/effect-app/src/Schema/SpecialJsonSchema.ts b/packages/effect-app/src/Schema/SpecialJsonSchema.ts index e99d1cd88..e2d95c730 100644 --- a/packages/effect-app/src/Schema/SpecialJsonSchema.ts +++ b/packages/effect-app/src/Schema/SpecialJsonSchema.ts @@ -25,10 +25,53 @@ export function specialJsonSchemaDocument( } } +const lowerBoundKeywords = new Set(["minimum", "exclusiveMinimum", "minLength", "minItems", "minProperties"]) +const upperBoundKeywords = new Set(["maximum", "exclusiveMaximum", "maxLength", "maxItems", "maxProperties"]) +const annotationKeywords = new Set([ + "title", + "description", + "default", + "examples", + "readOnly", + "writeOnly", + "deprecated", + "$comment" +]) +const isAnnotationKeyword = (key: string) => annotationKeywords.has(key) || key.startsWith("x-") + +// Every keyword of an `allOf` member applies, so a repeated bound reduces to its tighter value. +// Returns `undefined` on any other conflicting validation keyword: then the `allOf` is kept. +function mergeAllOfEntry( + merged: Record, + entry: Record +): Record | undefined { + const out = { ...merged } + for (const [key, value] of Object.entries(entry)) { + const current = out[key] + if (!(key in out) || isAnnotationKeyword(key)) { + out[key] = value + } else if (typeof current === "number" && typeof value === "number" && lowerBoundKeywords.has(key)) { + out[key] = Math.max(current, value) + } else if (typeof current === "number" && typeof value === "number" && upperBoundKeywords.has(key)) { + out[key] = Math.min(current, value) + } else if (JSON.stringify(current) !== JSON.stringify(value)) { + return undefined + } + } + if (typeof out["minimum"] === "number" && typeof out["exclusiveMinimum"] === "number") { + delete out[out["exclusiveMinimum"] >= out["minimum"] ? "minimum" : "exclusiveMinimum"] + } + if (typeof out["maximum"] === "number" && typeof out["exclusiveMaximum"] === "number") { + delete out[out["exclusiveMaximum"] <= out["maximum"] ? "maximum" : "exclusiveMaximum"] + } + return out +} + /** * Flattens `allOf` entries into the parent when the parent already has a * `type` and every `allOf` entry is a plain constraint object (no `$ref`, - * no `type`). Merged properties from `allOf` entries win on conflict. + * no `type`). Repeated bounds keep the tighter value, annotations from + * `allOf` entries win, and any other conflicting keyword keeps the `allOf`. */ export function flattenSimpleAllOf(obj: unknown): unknown { if (obj === null || typeof obj !== "object") return obj @@ -50,9 +93,10 @@ export function flattenSimpleAllOf(obj: unknown): unknown { ) if (canFlatten) { const { allOf: _, ...rest } = result - const merged: Record = { ...rest } + let merged: Record | undefined = rest for (const entry of allOf) { - Object.assign(merged, entry) + merged = mergeAllOfEntry(merged, entry) + if (merged === undefined) return result } return merged } diff --git a/packages/effect-app/src/Schema/numbers.ts b/packages/effect-app/src/Schema/numbers.ts index 020be91dd..38c0c38f1 100644 --- a/packages/effect-app/src/Schema/numbers.ts +++ b/packages/effect-app/src/Schema/numbers.ts @@ -160,3 +160,168 @@ export type NonNegativeDecimal = NonNegativeNumber export const PositiveDecimal = PositiveNumber /** @deprecated Not an actual decimal */ export type PositiveDecimal = PositiveNumber + +/** Signed 32-bit integer bounds, matching Java `Integer.MIN_VALUE` / `Integer.MAX_VALUE`. */ +export const INT32_MIN = -2147483648 +export const INT32_MAX = 2147483647 +/** + * Java's `Float.MAX_VALUE` literal `3.4028235E38` (as written by `Float.toString`). Rounds to the largest + * finite IEEE 754 binary32 value; anything accepted up to it stays finite in binary32 (no overflow). + */ +export const FLOAT32_MAX = 3.4028235e38 +/** + * Java's `Float.MIN_VALUE` literal `1.4E-45` (as written by `Float.toString`). Rounds to the smallest + * positive binary32 value (subnormal `2^-149`); anything accepted from it stays non-zero (no underflow). + */ +export const FLOAT32_MIN_POSITIVE = 1.4e-45 + +// The upper-bound check also carries the OpenAPI `format`, so Effect inlines it next to the +// tightened `minimum`/`maximum` instead of emitting a separate `allOf` member. +const isInt32Maximum = () => + S.isLessThanOrEqualTo(INT32_MAX, { toJsonSchema: () => ({ maximum: INT32_MAX, format: "int32" }) }) +const isFloat32Maximum = () => + S.isLessThanOrEqualTo(FLOAT32_MAX, { toJsonSchema: () => ({ maximum: FLOAT32_MAX, format: "float" }) }) + +export interface Int32Brand extends Simplify & IntBrand> {} +export type Int32 = number & Int32Brand +/** + * Signed 32-bit integer (`[-2147483648, 2147483647]`), JSON Schema `format: "int32"`. + * `.withConstructorDefault` => `0` (construction-only). + */ +export interface Int32Schema extends BrandedSchema { + (i: number, options?: SchemaAST.ParseOptions): Int32 + readonly withConstructorDefault: S.withConstructorDefault> +} +export const Int32: Int32Schema = extendM( + S.Int.pipe( + S.check(S.isGreaterThanOrEqualTo(INT32_MIN), isInt32Maximum()), + fromBrand(nominal(), { identifier: "Int32", jsonSchema: {} }), + withDefaultMake + ), + (s) => ({ + /** Construction-only default `0`. NOT applied during decode. See file-level note. */ + withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) + }) +) + +export interface NonNegativeInt32Brand + extends Simplify & Int32Brand & NonNegativeIntBrand & NonNegativeNumber32Brand> +{} +export type NonNegativeInt32 = number & NonNegativeInt32Brand +/** + * Non-negative signed 32-bit integer (`[0, 2147483647]`), JSON Schema `format: "int32"`. + * `.withConstructorDefault` => `0` (construction-only). + */ +export interface NonNegativeInt32Schema extends BrandedSchema { + (i: number, options?: SchemaAST.ParseOptions): NonNegativeInt32 + readonly withConstructorDefault: S.withConstructorDefault> +} +export const NonNegativeInt32: NonNegativeInt32Schema = extendM( + S.Int.pipe( + S.check(S.isGreaterThanOrEqualTo(0), isInt32Maximum()), + fromBrand(nominal(), { identifier: "NonNegativeInt32", jsonSchema: {} }), + withDefaultMake + ), + (s) => ({ + /** Construction-only default `0`. NOT applied during decode. See file-level note. */ + withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) + }) +) + +export interface PositiveInt32Brand + extends Simplify & NonNegativeInt32Brand & PositiveIntBrand & PositiveNumber32Brand> +{} +export type PositiveInt32 = number & PositiveInt32Brand +/** + * Positive signed 32-bit integer (`[1, 2147483647]`), JSON Schema `format: "int32"`. + * `.withConstructorDefault` => `1` (construction-only). + */ +export interface PositiveInt32Schema extends BrandedSchema { + (i: number, options?: SchemaAST.ParseOptions): PositiveInt32 + readonly withConstructorDefault: S.withConstructorDefault> +} +export const PositiveInt32: PositiveInt32Schema = extendM( + S.Int.pipe( + // `>= 1` rather than `> 0`: same integer set, but an inclusive `minimum` that Java generators keep exact + S.check(S.isGreaterThanOrEqualTo(1), isInt32Maximum()), + fromBrand(nominal(), { identifier: "PositiveInt32", jsonSchema: {} }), + withDefaultMake + ), + (s) => ({ + /** Construction-only default `1`. NOT applied during decode. See file-level note. */ + withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1)))) + }) +) + +export interface NonNegativeNumber32Brand extends Simplify & NonNegativeNumberBrand> {} +export type NonNegativeNumber32 = number & NonNegativeNumber32Brand +/** + * Non-negative finite number within IEEE 754 binary32 range (`[0, 3.4028235e38]`), + * JSON Schema `format: "float"`. + * + * Range-only: values are kept as-is (no rounding to binary32); a binary32 consumer rounds to its + * nearest float (~7 significant digits). Values above `FLOAT32_MAX` are rejected (overflow to + * `Infinity`, conservatively from Java's literal). Tiny values below `FLOAT32_MIN_POSITIVE` are accepted: + * they may underflow to `0` in binary32, which keeps them non-negative. `.withConstructorDefault` => `0` (construction-only). + */ +export interface NonNegativeNumber32Schema extends BrandedSchema { + (i: number, options?: SchemaAST.ParseOptions): NonNegativeNumber32 + readonly withConstructorDefault: S.withConstructorDefault> +} +export const NonNegativeNumber32: NonNegativeNumber32Schema = extendM( + S.Finite.pipe( + S.check( + S.isGreaterThanOrEqualTo(0, { + arbitraryConstraint: { order: Order.Number, minimum: 0, maximum: realisticMaximum } + }), + isFloat32Maximum() + ), + fromBrand(nominal(), { + identifier: "NonNegativeNumber32", + jsonSchema: {} + }), + withDefaultMake + ), + (s) => ({ + /** Construction-only default `0`. NOT applied during decode. See file-level note. */ + withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) + }) +) + +export interface PositiveNumber32Brand + extends Simplify & NonNegativeNumber32Brand & PositiveNumberBrand> +{} +export type PositiveNumber32 = number & PositiveNumber32Brand +/** + * Positive finite number within IEEE 754 binary32 range + * (`[1.4e-45, 3.4028235e38]`), JSON Schema `format: "float"`. + * + * Range-only: values are kept as-is (no rounding to binary32); a binary32 consumer rounds to its + * nearest float (~7 significant digits). Values above `FLOAT32_MAX` (overflow to `Infinity`) and + * values below `FLOAT32_MIN_POSITIVE` (underflow to `0`, losing positivity) are rejected, conservatively + * from Java's `Float` literals. + * `.withConstructorDefault` => `1` (construction-only). + */ +export interface PositiveNumber32Schema extends BrandedSchema { + (i: number, options?: SchemaAST.ParseOptions): PositiveNumber32 + readonly withConstructorDefault: S.withConstructorDefault> +} +export const PositiveNumber32: PositiveNumber32Schema = extendM( + S.Finite.pipe( + S.check( + S.isGreaterThanOrEqualTo(FLOAT32_MIN_POSITIVE, { + arbitraryConstraint: { order: Order.Number, minimum: FLOAT32_MIN_POSITIVE, maximum: realisticMaximum } + }), + isFloat32Maximum() + ), + fromBrand(nominal(), { + identifier: "PositiveNumber32", + jsonSchema: {} + }), + withDefaultMake + ), + (s) => ({ + /** Construction-only default `1`. NOT applied during decode. See file-level note. */ + withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1)))) + }) +) diff --git a/packages/effect-app/test/numbers32.test.ts b/packages/effect-app/test/numbers32.test.ts new file mode 100644 index 000000000..9bb03eef1 --- /dev/null +++ b/packages/effect-app/test/numbers32.test.ts @@ -0,0 +1,163 @@ +import * as S from "effect-app/Schema" +import { flattenSimpleAllOf, specialJsonSchemaDocument } from "effect-app/Schema/SpecialJsonSchema" +import { deduplicateOpenApiSchemas } from "effect-app/Schema/SpecialOpenApi" +import * as Arbitrary from "effect/Arbitrary" +import * as Effect from "effect/Effect" +import * as Exit from "effect/Exit" +import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api" +import { describe, expect, test } from "vitest" + +const { FLOAT32_MAX, FLOAT32_MIN_POSITIVE, INT32_MAX, INT32_MIN } = S +const binary32Max = (2 - 2 ** -23) * 2 ** 127 +// next double above FLOAT32_MAX (its ulp is 2^75) +const aboveFloat32Max = FLOAT32_MAX + 2 ** 75 +// genuine binary32 overflow / underflow +const overflows = 3.4028236e38 +const underflows = 7e-46 +const nonFinite = [NaN, Infinity, -Infinity] + +const cases = [ + { + name: "Int32", + schema: S.Int32, + accept: [INT32_MIN, -1, 0, 1, INT32_MAX], + reject: [INT32_MIN - 1, INT32_MAX + 1, Number.MAX_SAFE_INTEGER, 1.5, -0.5, ...nonFinite] + }, + { + name: "NonNegativeInt32", + schema: S.NonNegativeInt32, + accept: [0, 1, INT32_MAX], + reject: [-1, INT32_MIN, INT32_MAX + 1, 0.5, ...nonFinite] + }, + { + name: "PositiveInt32", + schema: S.PositiveInt32, + accept: [1, INT32_MAX], + reject: [0, -1, INT32_MAX + 1, 0.5, 1.5, ...nonFinite] + }, + { + name: "NonNegativeNumber32", + schema: S.NonNegativeNumber32, + // underflow to 0 in binary32 keeps the value non-negative: accepted + accept: [0, underflows, 2 ** -149, FLOAT32_MIN_POSITIVE, 0.1, 1.5, INT32_MAX + 0.5, binary32Max, FLOAT32_MAX], + reject: [-0.1, -FLOAT32_MIN_POSITIVE, aboveFloat32Max, overflows, Number.MAX_VALUE, ...nonFinite] + }, + { + name: "PositiveNumber32", + schema: S.PositiveNumber32, + accept: [FLOAT32_MIN_POSITIVE, 2 ** -149, 0.1, 1, 1.5, INT32_MAX + 0.5, binary32Max, FLOAT32_MAX], + reject: [0, -0.1, underflows, aboveFloat32Max, overflows, Number.MAX_VALUE, ...nonFinite] + } +] as const + +test("bounds match Java Integer / Float", () => { + expect(INT32_MIN).toBe(-(2 ** 31)) + expect(INT32_MAX).toBe(2 ** 31 - 1) + expect(INT32_MAX + 1 | 0).toBe(INT32_MIN) + // Java Float.toString(Float.MAX_VALUE / Float.MIN_VALUE) + expect(FLOAT32_MAX).toBe(Number("3.4028235E38")) + expect(FLOAT32_MIN_POSITIVE).toBe(Number("1.4E-45")) + expect(Math.fround(FLOAT32_MAX)).toBe(binary32Max) + expect(Math.fround(FLOAT32_MIN_POSITIVE)).toBe(2 ** -149) + expect(Math.fround(overflows)).toBe(Infinity) + expect(Math.fround(underflows)).toBe(0) +}) + +describe.each(cases)("$name", ({ accept, reject, schema }) => { + test("decode/encode accept boundaries, keeping fractions as-is", () => { + for (const n of accept) { + expect(S.decodeUnknownSync(schema)(n)).toBe(n) + expect(S.encodeUnknownSync(schema)(n)).toBe(n) + expect(schema(n)).toBe(n) + } + }) + + test("decode/encode reject out-of-range, fractions where integer, NaN and Infinity", () => { + for (const n of reject) { + expect(Exit.isFailure(S.decodeUnknownExit(schema)(n)), `decode ${n}`).toBe(true) + expect(Exit.isFailure(S.encodeUnknownExit(schema)(n)), `encode ${n}`).toBe(true) + expect(() => schema(n), `make ${n}`).toThrow() + } + }) + + test("native Arbitrary samples valid values", () => { + const samples = Effect.runSync(Arbitrary.sampleEffect(Arbitrary.schema(schema), { count: 100, seed: 1 })) + for (const n of samples) expect(S.is(schema)(n), `${n}`).toBe(true) + }) +}) + +test("withConstructorDefault is construction-only", () => { + const s = S.Struct({ + i: S.Int32.withConstructorDefault, + nni: S.NonNegativeInt32.withConstructorDefault, + pi: S.PositiveInt32.withConstructorDefault, + nnn: S.NonNegativeNumber32.withConstructorDefault, + pn: S.PositiveNumber32.withConstructorDefault + }) + expect(s.make({})).toStrictEqual({ i: 0, nni: 0, pi: 1, nnn: 0, pn: 1 }) + expect(Exit.isFailure(S.decodeUnknownExit(s)({}))).toBe(true) +}) + +test("brands extend the existing numeric brands", () => { + const pi: S.PositiveInt32 = S.PositiveInt32(1) + const nni: S.NonNegativeInt32 = pi + const i: S.Int32 = nni + const pn: S.PositiveNumber32 = pi + const nnn: S.NonNegativeNumber32 = pn + const wide: Array = [i, nni, S.NonNegativeInt(1), S.PositiveInt(1)] + const existing: [S.PositiveInt, S.NonNegativeInt, S.PositiveNumber, S.NonNegativeNumber] = [pi, nni, pn, nnn] + // @ts-expect-error Int is not bounded to 32 bit + const _narrow: S.Int32 = S.Int(1) + // @ts-expect-error PositiveNumber is not bounded to binary32 + const _narrowN: S.PositiveNumber32 = S.PositiveNumber(1) + expect([...wide, ...existing]).toHaveLength(8) +}) + +describe("JSON Schema / OpenAPI", () => { + const expected = { + Int32: { type: "integer", minimum: INT32_MIN, maximum: INT32_MAX, format: "int32" }, + NonNegativeInt32: { type: "integer", minimum: 0, maximum: INT32_MAX, format: "int32" }, + PositiveInt32: { type: "integer", minimum: 1, maximum: INT32_MAX, format: "int32" }, + NonNegativeNumber32: { type: "number", minimum: 0, maximum: FLOAT32_MAX, format: "float" }, + PositiveNumber32: { type: "number", minimum: FLOAT32_MIN_POSITIVE, maximum: FLOAT32_MAX, format: "float" } + } + + test.each(cases)("$name JSON Schema", ({ name, schema }) => { + expect(specialJsonSchemaDocument(schema).definitions[name]).toStrictEqual(expected[name]) + }) + + test("OpenAPI components keep 32-bit and existing schemas apart", () => { + const Payload = S.Struct({ + int: S.Int, + positiveInt: S.PositiveInt, + nonNegativeInt: S.NonNegativeInt, + int32: S.Int32, + positiveInt32: S.PositiveInt32, + nonNegativeInt32: S.NonNegativeInt32, + positiveNumber32: S.PositiveNumber32, + nonNegativeNumber32: S.NonNegativeNumber32 + }) + const api = HttpApi.make("api").add( + HttpApiGroup.make("g").add(HttpApiEndpoint.post("p", "/p", { payload: Payload })) + ) + const schemas = deduplicateOpenApiSchemas(OpenApi.fromApi(api))["components"]["schemas"] + expect(schemas).toStrictEqual({ + ...expected, + Int: { type: "integer", minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER }, + PositiveInt: { type: "integer", exclusiveMinimum: 0, maximum: Number.MAX_SAFE_INTEGER }, + NonNegativeInt: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER } + }) + }) + + test("flattenSimpleAllOf intersects bounds of composed checks", () => { + const doc = specialJsonSchemaDocument(S.Number.check(S.isInt32(), S.isGreaterThanOrEqualTo(0))) + expect(doc.schema).toStrictEqual({ type: "integer", minimum: 0, maximum: INT32_MAX }) + }) + + test("flattenSimpleAllOf keeps allOf on conflicting non-bound keywords", () => { + const input = { type: "string", format: "uuid", allOf: [{ format: "email" }] } + expect(flattenSimpleAllOf(input)).toStrictEqual(input) + expect(flattenSimpleAllOf({ type: "string", "x-a": 1, allOf: [{ "x-a": 2, deprecated: true }] })) + .toStrictEqual({ type: "string", "x-a": 2, deprecated: true }) + }) +})