@mikrojs/schema 0.0.0 → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Bjørge Næss
+
+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

@@ -0,0 +1,67 @@
+# @mikrojs/schema
+
+The schema DSL behind [Mikro.js](https://mikrojs.dev): declare a shape once, infer its
+TypeScript type, validate values against it, and serialize it as plain JSON for something
+else to read. Zero dependencies, no Node APIs, so it runs on Node, Bun, Deno, Cloudflare
+Workers and in a browser.
+
+Apps on a device import `mikro/schema` instead, which is this same DSL backed by a native
+module plus a `Result`-returning `parse()`. This package is the host half: the CLI evaluating
+`mikro.config.ts`, a registry validating what an operator saves, and anything else that needs
+to read a published schema.
+
+```js
+import {number, object, string, validate} from '@mikrojs/schema'
+
+const Config = object({
+  mqttUrl: string({title: 'Broker URL', format: 'url'}),
+  interval: number({title: 'Publish interval', unit: 's', default: 60, min: 1, max: 3600}),
+})
+
+validate(Config, {mqttUrl: 'mqtt://box.local', interval: 60}, '') // => null
+validate(Config, {mqttUrl: 'mqtt://box.local', interval: 0}, '')
+// => {ok: false, error: {name: 'ValidationFailed', message: 'below the minimum of 1', path: '.interval'}}
+```
+
+`validate()` returns `null` when the value is good, and covers shape plus every numeric and
+length bound. `format` is not checked here; see `@mikrojs/schema/config`.
+
+## Annotations
+
+Nodes carry annotations, and they divide in two. **Display** annotations (`title`,
+`description`, `mask`) describe how a value should be presented and never change what
+validates, so a consumer may ignore any it does not recognise. **Constraints** (`min`, `max`,
+`integer`, `minLength`, `maxLength`, `minItems`, `maxItems`, `format`, `unit`) do change what
+validates, and a consumer must not ignore one it does not recognise: ignoring a constraint
+means accepting a value the author ruled out.
+
+`unit` is a closed enum following [SenML](https://www.rfc-editor.org/rfc/rfc8428) with ASCII
+keys. It is a display hint and constrains nothing. Never convert a stored value through a
+unit's scale — see the note beside `UNITS`.
+
+## `@mikrojs/schema/config`
+
+The host-side machinery for Mikro.js OTA config, which is what a registry needs:
+
+- `validateConfig(schema, value)` — `validate()` plus `format`, returning `{ok, value}` or
+  `{ok: false, error}`
+- `parseConfigSchema(value)` — validate a schema that arrived as JSON, rejecting malformed
+  annotations and unknown `format` or `unit` values
+- `deriveOverlay` / `parseEffective` / `materializeDefaults` — the sparse-overlay model, where
+  a registry stores only deviations from the author's defaults and serves the complete document
+- `diffConfigSchemas(previous, next)` — what changed between two releases, and whether it needs
+  an operator's attention
+- `UNITS`, `FORMATS` — the unit table and the format names
+
+`format` lives here rather than in the main entry for two reasons: the expressions are a
+denial-of-service surface a device should not carry, and a device has no regular-expression
+engine to carry them with.
+
+The wire format is the contract. It is specified in the
+[OTA Registry Spec](https://mikrojs.dev/registry-spec) under "The config schema", and that
+document, not this package's version number, is what a third-party registry should build
+against.
+
+## Documentation
+
+[mikrojs.dev/api/schema](https://mikrojs.dev/api/schema)

package/dist/config.d.ts

@@ -0,0 +1,79 @@
+import { type Format, type Schema, SchemaError, type Unit } from './core.js';
+export type SchemaCheck<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: SchemaError;
+};
+export declare const FORMATS: readonly Format[];
+/**
+ * Validates a value against a config schema, `format` included. `validate()` in
+ * core.ts covers shape and every numeric and length bound; this adds the one
+ * annotation that stays host-side, so every path that validates an operator's
+ * value goes through here rather than calling validate() directly.
+ */
+export declare function validateConfig(schema: Schema, value: unknown): SchemaCheck<unknown>;
+/** How a unit relates to the primary it measures in, plus the symbol to render
+ *  when the ASCII key is not what a person should read.
+ *
+ *  `scale` and `offset` exist so a form can show a read-only hint beside a
+ *  field ("30000000 us (30 s)"). They MUST NOT be used to convert a stored
+ *  value. The registry stores only deviations from the schema defaults and
+ *  hashes the effective document for its rev, so a lossy round trip stops a
+ *  default-equal value being stripped and two operators entering the same
+ *  thing produce different revs. Having the numbers here makes converting look
+ *  easy; it is still wrong. */
+export interface UnitDefinition {
+    readonly primary: Unit;
+    readonly scale: number;
+    readonly offset: number;
+    readonly symbol?: string;
+}
+export declare const UNITS: Record<Unit, UnitDefinition>;
+/**
+ * Validates an untrusted serialized schema AST as a config schema: well-formed
+ * nodes only, an object at the root, no `unknown()`, no `optional()` around an
+ * object or array (an overlay needs every absence to mean exactly one thing),
+ * defaults that match their own node, and nesting of at most 8 levels.
+ * The size cap is the caller's, since only the caller sees encoded bytes.
+ */
+export declare function parseConfigSchema(value: unknown): SchemaCheck<Schema>;
+/**
+ * Derives the overlay to store or serve from operator-supplied values: drops
+ * keys the schema does not know, strips values structurally equal to the
+ * schema default, and prunes empty objects and arrays. Returns undefined when
+ * nothing deviates from the defaults. Wholesale nodes (arrays, tuples, unions)
+ * are compared and kept as units; nothing inside them is stripped.
+ */
+export declare function deriveOverlay(schema: Schema, values: unknown): unknown;
+export declare function structuralEquals(a: unknown, b: unknown): boolean;
+/**
+ * The effective config for an overlay: defaults filled in, then validated.
+ * What a registry runs before serving and what `ota.config()` runs on read.
+ */
+export declare function parseEffective(schema: Schema, overlay: unknown): SchemaCheck<unknown>;
+/**
+ * The partial defaults a schema materializes with no overrides: every field a
+ * default covers, and nothing else. Unlike parseEffective it never fails on a
+ * required defaultless field, it omits it. This is what pack bakes into the
+ * manifest and what a device reads when it holds no served document.
+ *
+ * Plain objects compose, so a nested one is included only when defaults fill
+ * it completely: a half-filled object would not validate, and the read type
+ * makes that field optional anyway. Wholesale units (array, tuple, union,
+ * taggedUnion) need a whole-value default on the node itself, matching
+ * applyDefaults, where a default inside an element or branch is a form hint.
+ * Optional fields rest on absence, so they are omitted too.
+ */
+export declare function materializeDefaults(schema: Schema): Record<string, unknown>;
+/**
+ * Human-readable warnings for what changed between two releases' config
+ * schemas, per the spec's change taxonomy (registry-spec.md, "Schema changes
+ * between releases"). Safe changes (new defaulted or optional fields, added
+ * union members, loosened requirements) produce nothing. "requires an
+ * operator" lines gate offers under rule 5 until someone supplies or fixes a
+ * value; "note" lines are compatible but worth telling the operator about.
+ */
+export declare function diffConfigSchemas(previous: Schema, next: Schema): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,MAAM,EAEX,KAAK,MAAM,EACX,WAAW,EACX,KAAK,IAAI,EAEV,MAAM,WAAW,CAAA;AAElB,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAC,CAAA;AAgBnF,eAAO,MAAM,OAAO,EAAmC,SAAS,MAAM,EAAE,CAAA;AAExE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAMnF;AA8ED;;;;;;;;;+BAS+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAKvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAKD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,CAoH9C,CAAA;AAkCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAOrE;AAoQD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAuCtE;AAkBD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAmBhE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAMrF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE3E;AA8LD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAoI1E"}