David
aa0ffd64ea
src/registry/ holds what the library knows about an interface: namespace, version, the page it was read from, properties with their value schemas and directives with their payload schemas. Five interfaces are described (Alexa, PowerController, BrightnessController, TemperatureSensor, EndpointHealth); the other 65 names of AlexaInterfaceType are stubs with the version and property names of 1.5.2. schema.ts is the run-time check behind it (241 lines, no new dependency), catalog.ts the vocabularies of the pages: 103 assets (23 units), 6 actions, 9 states, 56 display categories, 22 reserved words, 73 error types under 11 namespaces. AlexaInterface.getVersion() and getProps() read the registry; the two switch statements are gone (-167 lines). On the wire: Alexa.EndpointHealth is announced at 3.1 (was 3.3; the page is titled 3.1 and no page mentions 3.3), and TimeHoldController and Camera.LiveViewController at 3 and 1.7 (1.5.2 sent the string "UNKNOWN"). DisplayCategory gains VACUUM. New exports: registry, DeclarationError, SchemaError, Assets, Units, Actions, States, DisplayCategories and the descriptor types. Tests: 20 JSON examples of the five pages under test/fixtures/alexa-docs; every directive payload and property value in them parses with its descriptor. npm test: 57 pass (was 30) in 10.8 s, also on Node 18.20.8 and 20.20.2. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
91 lines
3.3 KiB
TypeScript
91 lines
3.3 KiB
TypeScript
/** A value that does not fit its schema: path is where ("payload.targetSetpoint.scale"), problem is what. */
|
|
export declare class SchemaError extends Error {
|
|
readonly path: string;
|
|
readonly problem: string;
|
|
constructor(path: string, problem: string);
|
|
}
|
|
export interface Schema<T> {
|
|
/** What the schema accepts, in the words of an error message: "an integer from 0 to 100", "ON | OFF". */
|
|
readonly expects: string;
|
|
/** The checked value. path names it in the error message. */
|
|
parse(input: unknown, path?: string): T;
|
|
}
|
|
/** A schema that accepts a missing value; s.object() makes its key optional in the inferred type. */
|
|
export interface OptionalSchema<T> extends Schema<T | undefined> {
|
|
readonly optional: true;
|
|
}
|
|
export interface EnumSchema<V> extends Schema<V> {
|
|
readonly values: readonly V[];
|
|
}
|
|
/** The type a schema produces. */
|
|
export type Infer<S> = S extends Schema<infer T> ? T : never;
|
|
export type Shape = Record<string, Schema<any>>;
|
|
type OptionalKeys<S extends Shape> = {
|
|
[K in keyof S]: S[K] extends OptionalSchema<any> ? K : never;
|
|
}[keyof S];
|
|
export type InferShape<S extends Shape> = {
|
|
[K in Exclude<keyof S, OptionalKeys<S>>]: Infer<S[K]>;
|
|
} & {
|
|
[K in OptionalKeys<S>]?: Infer<S[K]>;
|
|
};
|
|
export interface NumberRules {
|
|
min?: number;
|
|
max?: number;
|
|
/** Greater than, the bound itself excluded. */
|
|
gt?: number;
|
|
integer?: boolean;
|
|
}
|
|
export interface Temperature {
|
|
value: number;
|
|
scale: "CELSIUS" | "FAHRENHEIT" | "KELVIN";
|
|
}
|
|
export interface TimeInterval {
|
|
start?: string;
|
|
end?: string;
|
|
duration?: string;
|
|
}
|
|
declare function number(rules?: NumberRules): Schema<number>;
|
|
declare function string(rules?: {
|
|
min?: number;
|
|
max?: number;
|
|
pattern?: RegExp;
|
|
expects?: string;
|
|
}): Schema<string>;
|
|
declare function boolean(): Schema<boolean>;
|
|
declare function literal<V extends string | number | boolean | null>(value: V): Schema<V>;
|
|
declare function enumeration<V extends readonly string[]>(...values: V): EnumSchema<V[number]>;
|
|
declare function unknown(): Schema<unknown>;
|
|
declare function optional<T>(inner: Schema<T>): OptionalSchema<T>;
|
|
declare function nullable<T>(inner: Schema<T>): Schema<T | null>;
|
|
declare function array<T>(item: Schema<T>, rules?: {
|
|
min?: number;
|
|
max?: number;
|
|
}): Schema<T[]>;
|
|
/**
|
|
* An object with the keys of shape. Keys the shape does not name are kept as they are: a field Alexa adds to a
|
|
* directive reaches the handler. unknownKeys "reject" is for what a developer writes, where such a key is a typo.
|
|
*/
|
|
declare function object<S extends Shape>(shape: S, rules?: {
|
|
unknownKeys?: "keep" | "reject";
|
|
}): Schema<InferShape<S>>;
|
|
declare function temperature(): Schema<Temperature>;
|
|
declare function dateTime(): Schema<string>;
|
|
declare function duration(): Schema<string>;
|
|
declare function timeInterval(): Schema<TimeInterval>;
|
|
export declare const s: {
|
|
string: typeof string;
|
|
number: typeof number;
|
|
boolean: typeof boolean;
|
|
literal: typeof literal;
|
|
enum: typeof enumeration;
|
|
unknown: typeof unknown;
|
|
optional: typeof optional;
|
|
nullable: typeof nullable;
|
|
array: typeof array;
|
|
object: typeof object;
|
|
temperature: typeof temperature;
|
|
dateTime: typeof dateTime;
|
|
duration: typeof duration;
|
|
timeInterval: typeof timeInterval;
|
|
};
|
|
export {};
|