@jarenjs/formats 0.8.4 → 0.34.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Joham
+
+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/README.md

@@ -1,3 +1,144 @@
-# Jaren Validator Formats Package
+# @jarenjs/formats
 
-**this is a working package in need of documentation**
+Format validators for the JSON Schema `format` keyword, built on the text validators of [`@jarenjs/core`](../core). Includes all standard string formats (`date-time`, `date`, `time`, `duration`, `email`, `idn-email`, `hostname`, `idn-hostname`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template`, `iri`, `iri-reference`, `uuid`, `regex`) plus many extras (`iregexp`, `isbn10`, `mac`, `base64`, `alpha`, `color`, ...) and numeric formats (`int8` ... `uint64`, `float16` ... `float64`).
+
+The JSON addressing formats are grouped separately in `jsonFormats`: `json-pointer`, `json-pointer-uri-fragment` and `relative-json-pointer` (RFC 6901), and `json-path`, which validates query strings against the complete [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html) grammar using the parser of the JSONPath compiler in `@jarenjs/json`, plus `json-path-segments` for the variable-rooted path strings of the Jaren query format.
+
+The geospatial formats are grouped in `geoFormats`: `geohash`, `wkt` and `geojson`, backed by the spatial kernel in `@jarenjs/core/geo`.
+
+The name → predicate bindings live in one canonical table, exported as `formatTesters` (plus the per-group `stringFormatTesters`, `jsonFormatTesters`, `geoFormatTesters`, `dateTimeFormatTesters`, `numberFormatTesters`): bare synchronous predicates without validator coupling. The format compilers above wrap these testers in the validator contract, and [`@jarenjs/forms`](../forms) merges its rendering hints over the same table for per-keystroke field validation — one registry, so the two layers can never drift apart.
+
+## Usage
+
+```javascript
+import { JarenValidator } from '@jarenjs/validate';
+import * as formats from '@jarenjs/formats';
+
+const jaren = new JarenValidator()
+  .addFormats(formats.stringFormats)
+  .addFormats(formats.numberFormats)
+  .addFormats(formats.dateTimeFormats)
+  .addFormats(formats.jsonFormats)
+  .addFormats(formats.geoFormats);
+
+const validate = jaren.compile({ type: 'string', format: 'json-path' });
+validate('$.store.book[?@.price < 10]'); // true
+```
+
+Format assertion follows the specification per draft: asserted through draft 2019-09, annotation-only from draft 2020-12 on unless enabled via the `formatAssertion` option (`new JarenValidator({ formatAssertion: true })`) or a metaschema that declares the `format-assertion` vocabulary.
+
+**Register the group before you use a name from it, and register the right one.** The groups are split, so `date-time` lives in `dateTimeFormats` and *not* in `stringFormats`, and `json-path` lives in `jsonFormats`. Registering only `stringFormats` and then writing `format: 'date-time'` leaves the keyword accepting every value — per spec, an unregistered format is an annotation and asserts nothing, so nothing anywhere reports it. For schemas you own, compile with `new JarenValidator({ unknownFormats: 'error' })`: the missing registration then fails at compile time instead of silently. This repository does that for every schema it ships, gated by `test/validate/our-schema-formats.test.js`.
+
+**Register the compilers, not the testers.** `stringFormats` and `formatTesters` are both objects full of functions, but only the *compilers* take `(schemaObj, jsonSchema)` and return the per-value validator; a tester registered in a compiler's place compiles to nothing. That one throws under either `unknownFormats` setting, because it is never intentional. Use `formatTesters` directly — as [`@jarenjs/forms`](../forms) does for per-keystroke field validation — rather than through `addFormats`.
+
+## ✍ The complete format list
+
+### ✍ Formats for strings
+
+These format validators are based on the [json-schema.org](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats) website. They are grouped in `stringFormats` (with the date/time formats also available separately as `dateTimeFormats`).
+
+#### 🗨 Formats for datetime
+
+- `date-time` | according to [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), time-zone is mandatory
+- `date` | according to [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), time-zone is mandatory
+- `time` | according to [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), time-zone is mandatory
+
+- `duration` | duration from RFC3339
+- `iso-date-time` | ISO 8601 date-time with optional timezone
+- `iso-time` | ISO 8601 time with optional timezone — the timezone offset is uniformly optional, so a zone-less time such as `12:30:00` validates
+
+*Note: All date time formats can use formatMinimum / formatMaximum and formatExclusiveMinimum and formatExclusiveMaximum. The bounds are folded to epoch milliseconds at compile time and string values compare as numbers, so a validation allocates no `Date`; a raw `Date` instance as the value is still accepted and compares numerically.*
+
+#### 🗨 Formats for url's, hostnames and emails
+
+- `url` | http/https URL — a `uri` narrowed to the web schemes, so it must carry an authority and the RFC 3986 grammar still applies (`http://localhost:8080` and `http://127.0.0.1/` are URLs; `http://x/a|b` is not)
+- `uri` | full URI according to [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986), parsed against the grammar by character code — an ASCII grammar throughout, so a string carrying non-ASCII characters is an `iri` and not a `uri`
+- `uri-reference` | URI reference, absolute or relative, according to [RFC3986](https://datatracker.ietf.org/doc/html/rfc3986)
+- `uri-template` | URI template according to [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570)
+- `iri` | full URI with international characters, according to [RFC3987](https://datatracker.ietf.org/doc/html/rfc3987) — parsed against the grammar by character code, so percent-encoding must be well formed and `iprivate` is accepted in the query only
+- `iri-reference` | full IRI reference, absolute or relative, according to [RFC3987](https://datatracker.ietf.org/doc/html/rfc3987)
+
+- `email` | email address according to [RFC5321](https://datatracker.ietf.org/doc/html/rfc5321), including quoted-string local parts and `[192.0.2.1]` / `[IPv6:::1]` address literals
+- `hostname` | host name according to [RFC1034](https://datatracker.ietf.org/doc/html/rfc1034#section-3.5)
+- `idn-hostname` | host name with international characters
+- `idn-email` | email address with international characters
+
+#### 🗨 Formats for identifiers
+
+- `uuid` | Universally Unique IDentifier according to [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122)
+- `guid` | Globally Unique IDentifier according to Microsoft
+
+- `identifier` | C-type identifier
+- `html-identifier` | html element `id` attribute identifier according to [RFC7992](https://datatracker.ietf.org/doc/html/rfc7992#section-5.1)
+- `css-identifier` | css class name identifier according to [RFC7993](https://datatracker.ietf.org/doc/html/rfc7993)
+
+- `mac` | ethernet interface identifier (EUI-48) according to [IEEE820](https://en.wikipedia.org/wiki/MAC_address)
+- `ipv4` | IP v4 address according to [RFC791](https://datatracker.ietf.org/doc/html/rfc791)
+- `ipv6` | IP v6 address according to [RFC2460](https://datatracker.ietf.org/doc/html/rfc2460)
+
+#### 🗨 Formats for json pointers and paths
+
+These are grouped in `jsonFormats`.
+
+- `json-pointer` | JSON-pointer according to [RFC6901](https://datatracker.ietf.org/doc/html/rfc6901)
+- `json-pointer-uri-fragment` | JSON-pointer fragment according to [RFC6901](https://datatracker.ietf.org/doc/html/rfc6901#section-6)
+- `relative-json-pointer` | relative JSON-pointer according to [draft-luff-relative-json-pointer-00](https://datatracker.ietf.org/doc/html/draft-luff-relative-json-pointer-00)
+- `json-path` | JSONPath query according to [RFC9535](https://www.rfc-editor.org/rfc/rfc9535.html), checked against the complete grammar (including filter well-typedness) by the parser of the JSONPath compiler in `@jarenjs/json`
+- `json-path-segments` | a variable-rooted path string — `$name` followed by optional [RFC9535](https://www.rfc-editor.org/rfc/rfc9535.html) segments (`$book.price[?@.isbn]`), the form the Jaren query format uses to address a bound variable. Not a valid RFC 9535 query on its own (the RFC's root identifier is `$` alone), so `json-path` rejects it; both formats recognize the five built-in function extensions and no others, because a format has to mean the same thing in every schema
+
+#### 🗨 Miscellaneous formats
+
+- `alpha` | allow only ASCII alpha characters (a-zA-Z)
+- `numeric` | allow only numeric characters (0-9)
+- `alphanumeric` | allow only ASCII alpha numeric characters
+- `hexadecimal` | allow only hexadecimal characters (0-9a-fA-F)
+- `uppercase` | allow only upper case alpha characters
+- `lowercase` | allow only lower case alpha characters
+- `color` | web color hex string (starts with #, must be 3 or 6 hax characters)
+- `regex` | tests whether a string is a valid regular expression
+- `iregexp` | tests whether a string is a valid I-Regexp according to [RFC9485](https://www.rfc-editor.org/rfc/rfc9485.html) — the interoperable subset that means the same thing in every regexp dialect, so it is stricter than `regex`: shorthand classes (`\d`, `\w`), lazy quantifiers, anchors and lookaround are all rejected
+- `base64` | base64 encoded data
+- `byte` | same as `base64` format
+
+- `isbn10` | International Standard Book Number 10 digit number
+- `isbn13` | International Standard Book Number 13 digit number
+
+- `country2` | country code by alpha-2 according to [ISO3166-1](https://www.iso.org/iso-3166-country-codes.html) — the 249 assigned codes plus `XK`, the user-assigned code for Kosovo; matched case-insensitively
+- `iban` | International Bank Account Number according to [ISO13616](https://www.iso.org/standard/81090.html) — checks the country's registered length, the alphanumeric body and the ISO 7064 MOD 97-10 check digits, so a transposed digit is caught; accepts both the compact electronic format (`NL91ABNA0417164300`) and the print format grouped in fours (`NL91 ABNA 0417 1643 00`)
+
+### ✍ Geospatial formats
+
+These are grouped in `geoFormats`, backed by the spatial kernel in [`@jarenjs/core/geo`](../core).
+
+- `geohash` | a base-32 geohash cell name, any length (`u173z`); the alphabet is lowercase and deliberately omits `a`, `i`, `l` and `o`
+- `wkt` | a Well-Known Text geometry (ISO 19125 / OGC Simple Features): the seven tagged types with optional `Z`/`M`/`ZM` modifiers, `EMPTY`, consistent coordinate counts and closed polygon rings; an unmodified tag accepts 2 or 3 coordinates per point, as the field (PostGIS) does
+- `geojson` | a structurally valid GeoJSON object per [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946) — unlike every other format this one applies to **objects**, and it enforces the invariant JSON Schema provably cannot: every linear ring closed
+
+`geojson` exists *next to* the GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json), not instead of them, and the division of labour is deliberate: the format is the one-keyword annotation that answers yes or no in a single call, while the meta-schema locates the failure and (in the `$query`-extended variant) also checks ring winding. Reach for the schema when you want a diagnosis; reach for the format when you only want the gate.
+
+### ✍ Formats for numbers
+
+These are grouped in `numberFormats`. Formats for numbers validate both numbers and strings as number types; combine them with the `type` keyword (e.g. `{ "type": "integer", "format": "int32" }`) when only real number types should be allowed.
+
+#### 🗨 Formats integer numbers
+
+- `int8` | signed 8 bit integer
+- `uint8` | unsigned 8 bit integer
+- `int16` | signed 16 bit integer
+- `uint16` | unsigned 16 bit integer
+- `int32` | signed 32 bit integer
+- `uint32` | unsigned 32 integer
+- `int64` | signed 64 integer
+- `uint64` | unsigned 64 integer
+
+#### 🗨 Formats floating point numbers
+
+- `float16` | 16 bit floating point number
+- `float32` | 32 bit floating point number
+- `float64` | 64 bit floating point number
+- `float` | 32 bit floating point number
+- `double` | 64 bit floating point number
+
+## Development
+
+Unit tests live in `test/formats/` at the repository root; `test/formats/testers.test.js` enforces that every compiler registry's key set equals its tester group's, so the validator layer and the bare-predicate layer can never drift. The predicates themselves are implemented and tested in [`@jarenjs/core`](../core). See the repository [README](../../README.md) for the monorepo picture and the [ROADMAP](../../docs/ROADMAP.md) for planned formats.

package/dist/types/datetime.d.ts

@@ -0,0 +1,109 @@
+export type JSONSchema = {
+    format?: string;
+    formatMinimum?: string;
+    formatExclusiveMinimum?: string;
+    formatMaximum?: string;
+    formatExclusiveMaximum?: string;
+};
+export type ValidationObject = {
+    options: {
+        skipErrors: boolean;
+    };
+    createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean;
+};
+/**
+ * Compiles a validator for the 'date-time' format.
+ * Validates date-time strings per RFC 3339 (ISO 8601 profile).
+ * Supports formatMinimum, formatMaximum, formatExclusiveMinimum, formatExclusiveMaximum.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileDateTimeFormat(schemaObj, { format: 'date-time' })('2024-01-15T12:30:00Z'); // true
+ * compileDateTimeFormat(schemaObj, { format: 'date-time' })('2024-01-15T12:30:00+01:00'); // true
+ * compileDateTimeFormat(schemaObj, { format: 'date-time' })('invalid'); // false (with error)
+ */
+export declare function compileDateTimeFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'date' format.
+ * Validates date-only strings (YYYY-MM-DD) per RFC 3339.
+ * Supports formatMinimum, formatMaximum, formatExclusiveMinimum, formatExclusiveMaximum.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileDateOnlyFormat(schemaObj, { format: 'date' })('2024-01-15'); // true
+ * compileDateOnlyFormat(schemaObj, { format: 'date' })('2024-13-45'); // false (with error)
+ */
+export declare function compileDateOnlyFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'time' format.
+ * Validates time-only strings (HH:MM:SS or HH:MM:SS.sss) per RFC 3339.
+ * Supports formatMinimum, formatMaximum, formatExclusiveMinimum, formatExclusiveMaximum.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileTimeOnlyFormat(schemaObj, { format: 'time' })('12:30:00'); // true
+ * compileTimeOnlyFormat(schemaObj, { format: 'time' })('12:30:00.123'); // true
+ * compileTimeOnlyFormat(schemaObj, { format: 'time' })('25:00:00'); // false (with error)
+ */
+export declare function compileTimeOnlyFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'duration' format.
+ * Validates duration strings per RFC 3339.
+ * Format: P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W
+ * Examples: P1Y2M3DT4H5M6S, P1W, PT1H
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileDurationFormat(schemaObj, { format: 'duration' })('P1Y2M3DT4H5M6S'); // true
+ * compileDurationFormat(schemaObj, { format: 'duration' })('P1W'); // true
+ * compileDurationFormat(schemaObj, { format: 'duration' })('PT1H30M'); // true
+ * compileDurationFormat(schemaObj, { format: 'duration' })('P'); // false (with error)
+ */
+export declare function compileDurationFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'iso-date-time' format.
+ * Validates ISO 8601 date-time strings with optional timezone.
+ * Unlike RFC 3339 date-time, the timezone is optional.
+ * Supports formatMinimum, formatMaximum, formatExclusiveMinimum, formatExclusiveMaximum.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileISODateTimeFormat(schemaObj, { format: 'iso-date-time' })('2024-01-15T12:30:00Z'); // true
+ * compileISODateTimeFormat(schemaObj, { format: 'iso-date-time' })('2024-01-15T12:30:00+01:00'); // true
+ * compileISODateTimeFormat(schemaObj, { format: 'iso-date-time' })('2024-01-15T12:30:00'); // true (no timezone)
+ * compileISODateTimeFormat(schemaObj, { format: 'iso-date-time' })('2024-13-15T12:30:00'); // false (with error)
+ */
+export declare function compileISODateTimeFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'iso-time' format.
+ * Validates ISO 8601 time strings with optional timezone.
+ * Unlike RFC 3339 time, the timezone is optional.
+ * Supports formatMinimum, formatMaximum, formatExclusiveMinimum, formatExclusiveMaximum.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileISOTimeFormat(schemaObj, { format: 'iso-time' })('12:30:00Z'); // true
+ * compileISOTimeFormat(schemaObj, { format: 'iso-time' })('12:30:00+01:00'); // true
+ * compileISOTimeFormat(schemaObj, { format: 'iso-time' })('12:30:00'); // true (no timezone)
+ * compileISOTimeFormat(schemaObj, { format: 'iso-time' })('25:00:00'); // false (with error)
+ */
+export declare function compileISOTimeFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Object mapping date/time format names to their compiler functions.
+ * Used for backward compatibility and aggregate imports.
+ *
+ * @type {Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>}
+ */
+export declare const formatValidators: Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>;

package/dist/types/geo.d.ts

@@ -0,0 +1,77 @@
+export type JSONSchema = {
+    format?: string;
+    formatMinimum?: string;
+    formatExclusiveMinimum?: string;
+    formatMaximum?: string;
+    formatExclusiveMaximum?: string;
+};
+export type ValidationObject = {
+    options: {
+        skipErrors: boolean;
+    };
+    createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean;
+};
+/**
+ * @typedef {{format?: string, formatMinimum?: string, formatExclusiveMinimum?: string, formatMaximum?: string, formatExclusiveMaximum?: string}} JSONSchema
+ * @typedef {{
+ *   options: {skipErrors: boolean},
+ *   createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean
+ * }} ValidationObject
+ */
+/**
+ * Compiles a validator for the 'geohash' format.
+ * Validates geohash strings: any length, every character in the
+ * base-32 geohash alphabet.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileGeohashFormat(schemaObj, { format: 'geohash' })('u173z'); // true
+ * compileGeohashFormat(schemaObj, { format: 'geohash' })('u17a'); // false ('a' is not in the alphabet)
+ */
+export declare const compileGeohashFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'wkt' format.
+ * Validates Well-Known Text geometry strings (ISO 19125 / OGC Simple
+ * Features): the seven tagged geometry types with optional Z/M/ZM
+ * modifiers, consistent coordinate counts, and closed polygon rings.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileWktFormat(schemaObj, { format: 'wkt' })('POINT (4.9041 52.3676)'); // true
+ * compileWktFormat(schemaObj, { format: 'wkt' })('POLYGON ((0 0, 4 0, 4 4, 1 1))'); // false (open ring)
+ */
+export declare const compileWktFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'geojson' format. Unlike the string
+ * formats, this one applies to **objects**: any non-array object must be
+ * a structurally valid GeoJSON object (RFC 7946) — the coordinate
+ * nesting its `type` requires, positions inside the WGS 84 bounds, and
+ * every linear ring closed. Non-object values pass, following the rule
+ * that a format constrains only its own type.
+ *
+ * This is the quick, shallow judgment; the GeoJSON meta-schema artifacts
+ * in `@jarenjs/json` validate the same grammar more thoroughly (locating
+ * the failure, and — in the Jaren-extended variant — checking ring
+ * winding through `$query`). Reach for the schema when you want to know
+ * *what* is wrong; reach for the format when a one-keyword annotation is
+ * worth more than a diagnosis.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileGeoJsonFormat(schemaObj, { format: 'geojson' })({ type: 'Point', coordinates: [4.9, 52.4] }); // true
+ * compileGeoJsonFormat(schemaObj, { format: 'geojson' })({ type: 'Polygon', coordinates: [[[0,0],[1,0],[1,1],[2,2]]] }); // false (open ring)
+ * compileGeoJsonFormat(schemaObj, { format: 'geojson' })('not an object'); // true (wrong type is not this format's business)
+ */
+export declare function compileGeoJsonFormat(schemaObj: ValidationObject, jsonSchema: JSONSchema): (data: unknown, dataPath?: string) => boolean;
+/**
+ * Object mapping geospatial format names to their compiler functions.
+ *
+ * @type {Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>}
+ */
+export declare const formatValidators: Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>;

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+export type FormatValidator = (data: unknown, dataPath?: string) => boolean;
+export type FormatCompiler = (schemaObj: import('./string.js').ValidationObject, jsonSchema: import('./string.js').JSONSchema) => FormatValidator;
+/**
+ * A compiled format validator: tests one instance value against the
+ * format. `dataPath` is the value's RFC 6901 location, used in error
+ * reporting when error collection is enabled.
+ * @typedef {(data: unknown, dataPath?: string) => boolean} FormatValidator
+ */
+/**
+ * A format compiler as consumed by the JarenValidator's addFormat and
+ * addFormats methods of @jarenjs/validate: called once per schema
+ * location at compile time with the compiling validation object and the
+ * schema declaring the format, it returns the FormatValidator invoked for
+ * each instance value. Typed structurally so @jarenjs/formats stays free
+ * of a dependency on @jarenjs/validate.
+ * @typedef {(schemaObj: import('./string.js').ValidationObject, jsonSchema: import('./string.js').JSONSchema) => FormatValidator} FormatCompiler
+ */
+export { formatValidators as dateTimeFormats } from './datetime.js';
+export { formatValidators as stringFormats } from './string.js';
+export { formatValidators as numberFormats } from './number.js';
+export { formatValidators as jsonFormats } from './json.js';
+export { formatValidators as geoFormats } from './geo.js';
+export { formatTesters, stringFormatTesters, jsonFormatTesters, geoFormatTesters, dateTimeFormatTesters, numberFormatTesters, } from './testers.js';

package/dist/types/json.d.ts

@@ -0,0 +1,95 @@
+export type JSONSchema = {
+    format?: string;
+    formatMinimum?: string;
+    formatExclusiveMinimum?: string;
+    formatMaximum?: string;
+    formatExclusiveMaximum?: string;
+};
+export type ValidationObject = {
+    options: {
+        skipErrors: boolean;
+    };
+    createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean;
+};
+/**
+ * @typedef {{format?: string, formatMinimum?: string, formatExclusiveMinimum?: string, formatMaximum?: string, formatExclusiveMaximum?: string}} JSONSchema
+ * @typedef {{
+ *   options: {skipErrors: boolean},
+ *   createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean
+ * }} ValidationObject
+ */
+/**
+ * Compiles a validator for the 'json-pointer' format.
+ * Validates JSON Pointer strings per RFC 6901.
+ *
+ * @param {ValidationObject} schemaObj - The validation JSONSchema for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileJsonPointerFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'json-pointer-uri-fragment' format.
+ * Validates JSON Pointer URI fragment strings (e.g., #/foo/bar).
+ *
+ * @param {ValidationObject} schemaObj - The validation JSONSchema for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileJsonPointerUriFragmentFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'relative-json-pointer' format.
+ * Validates Relative JSON Pointer strings.
+ *
+ * @param {ValidationObject} schemaObj - The validation JSONSchema for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileRelativeJsonPointerFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'json-path' format.
+ * Validates JSONPath query expressions strictly against the complete
+ * RFC 9535 grammar, using the parser of the JSONPath compiler in
+ * `@jarenjs/json`. This includes the well-typedness rules for
+ * function expressions, so queries like `$[?length(@)]` or comparisons
+ * against non-singular queries are rejected.
+ *
+ * @param {ValidationObject} schemaObj - The validation JSONSchema for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileJsonPathFormat(schemaObj, { format: 'json-path' })('$.store.book[0].title'); // true
+ * compileJsonPathFormat(schemaObj, { format: 'json-path' })("$..book[?@.price < 10]"); // true
+ * compileJsonPathFormat(schemaObj, { format: 'json-path' })('@.name'); // false (queries start at $)
+ * compileJsonPathFormat(schemaObj, { format: 'json-path' })('$.foo '); // false (trailing whitespace)
+ */
+export declare const compileJsonPathFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'json-path-segments' format.
+ * Validates a *variable-rooted* path string: `$name` followed by
+ * optional RFC 9535 segments (`$book.price[?@.isbn]`). Such a string is
+ * not a valid RFC 9535 query — the RFC's root identifier is `$` alone —
+ * so `json-path` would reject it; this format is what gives the Jaren
+ * query format's variable-rooted paths the same schema-time
+ * well-formedness that absolute paths get from `json-path`.
+ *
+ * Both formats recognize the five built-in function extensions and no
+ * others: a format is a property of the string itself, so it must mean
+ * the same thing in every schema regardless of which custom extensions
+ * a particular host registered.
+ *
+ * @param {ValidationObject} schemaObj - The validation JSONSchema for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileJsonPathSegmentsFormat(schemaObj, { format: 'json-path-segments' })('$book.price'); // true
+ * compileJsonPathSegmentsFormat(schemaObj, { format: 'json-path-segments' })('$book'); // true
+ * compileJsonPathSegmentsFormat(schemaObj, { format: 'json-path-segments' })('$.price'); // false (that is json-path)
+ * compileJsonPathSegmentsFormat(schemaObj, { format: 'json-path-segments' })('$book.price['); // false
+ */
+export declare const compileJsonPathSegmentsFormat: (schemaObj: import("./string.js").ValidationObject, jsonSchema: import("./string.js").JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Object mapping JSON-related format names to their compiler functions.
+ *
+ * @type {Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>}
+ */
+export declare const formatValidators: Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>;

package/dist/types/number.d.ts

@@ -0,0 +1,144 @@
+export type JSONSchema = {
+    format?: string;
+    formatMinimum?: string;
+    formatExclusiveMinimum?: string;
+    formatMaximum?: string;
+    formatExclusiveMaximum?: string;
+};
+export type ValidationObject = {
+    options: {
+        skipErrors: boolean;
+    };
+    createErrorHandler: (expected: any, key: string, ...details: any[]) => (data: any, dataPath?: string) => boolean;
+};
+/**
+ * Compiles a validator for the 'int8' format.
+ * Validates 8-bit signed integers (-128 to 127).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileInt8Format(schemaObj, { format: 'int8' })(127); // true
+ * compileInt8Format(schemaObj, { format: 'int8' })(128); // false (with error)
+ * compileInt8Format(schemaObj, { format: 'int8' })('64'); // true (coerced)
+ */
+export declare const compileInt8Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'int16' format.
+ * Validates 16-bit signed integers (-32768 to 32767).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileInt16Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'int32' format.
+ * Validates 32-bit signed integers (-2147483648 to 2147483647).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileInt32Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'int64' format.
+ * Validates 64-bit signed integers (approximate range in JavaScript).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileInt64Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'uint8' format.
+ * Validates 8-bit unsigned integers (0 to 255).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ * @example
+ * compileUInt8Format(schemaObj, { format: 'uint8' })(255); // true
+ * compileUInt8Format(schemaObj, { format: 'uint8' })(256); // false (with error)
+ */
+export declare const compileUInt8Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'uint16' format.
+ * Validates 16-bit unsigned integers (0 to 65535).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileUInt16Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'uint32' format.
+ * Validates 32-bit unsigned integers (0 to 4294967295).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileUInt32Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'uint64' format.
+ * Validates 64-bit unsigned integers (approximate range in JavaScript).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileUInt64Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'float16' format.
+ * Validates 16-bit floating point numbers (IEEE 754 half-precision).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileFloat16Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'float32' format.
+ * Validates 32-bit floating point numbers (IEEE 754 single-precision).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileFloat32Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'float64' format.
+ * Validates 64-bit floating point numbers (IEEE 754 double-precision).
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileFloat64Format: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'float' format.
+ * Alias for 'float32' - validates 32-bit floating point numbers.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileFloatFormat: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Compiles a validator for the 'double' format.
+ * Alias for 'float64' - validates 64-bit floating point numbers.
+ *
+ * @param {ValidationObject} schemaObj - The validation object for error handling and options
+ * @param {JSONSchema} jsonSchema - The JSON schema containing the format definition
+ * @returns {(data: unknown, dataPath?: string) => boolean} A validator function
+ */
+export declare const compileDoubleFormat: (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean;
+/**
+ * Object mapping number format names to their compiler functions.
+ * Used for backward compatibility and aggregate imports.
+ *
+ * @type {Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>}
+ */
+export declare const formatValidators: Record<string, (schemaObj: ValidationObject, jsonSchema: JSONSchema) => (data: unknown, dataPath?: string) => boolean>;