yedra 0.20.11 → 0.20.13

package/dist/src/schema-lib.js

@@ -0,0 +1,20 @@
+// Browser-safe schema-only exports.
+// This module excludes all Node.js-specific code (HTTP server,
+// WebSocket, streams, etc.) so it can be safely bundled for the browser.
+export { BodyType } from './validation/body.js';
+export { boolean } from './validation/boolean.js';
+export { date } from './validation/date.js';
+export { _enum as enum } from './validation/enum.js';
+export { ValidationError } from './validation/error.js';
+export { integer } from './validation/integer.js';
+export { lazy, LazySchema } from './validation/lazy.js';
+export { array } from './validation/modifiable.js';
+export { _null as null } from './validation/null.js';
+export { number } from './validation/number.js';
+export { laxObject, object } from './validation/object.js';
+export { record } from './validation/record.js';
+export { Schema } from './validation/schema.js';
+export { string } from './validation/string.js';
+export { union } from './validation/union.js';
+export { unknown } from './validation/unknown.js';
+export { uuid } from './validation/uuid.js';

package/dist/src/schema.d.ts

@@ -0,0 +1,2 @@
+import * as y from './schema-lib.js';
+export { y };

package/dist/src/schema.js

@@ -0,0 +1,4 @@
+// Browser-safe entry point for frontend use.
+// Usage: import { y } from 'yedra/schema'
+import * as y from './schema-lib.js';
+export { y };

package/dist/src/util/counter.d.ts

@@ -0,0 +1,7 @@
+export declare class Counter {
+    private count;
+    private resolve;
+    wait(): Promise<void>;
+    increment(): void;
+    decrement(): void;
+}

package/dist/src/util/counter.js

@@ -0,0 +1,24 @@
+export class Counter {
+    constructor() {
+        this.count = 0;
+    }
+    wait() {
+        return new Promise((resolve) => {
+            if (this.count === 0) {
+                resolve();
+            }
+            else {
+                this.resolve = resolve;
+            }
+        });
+    }
+    increment() {
+        this.count += 1;
+    }
+    decrement() {
+        this.count -= 1;
+        if (this.count === 0 && this.resolve !== undefined) {
+            this.resolve();
+        }
+    }
+}

package/dist/src/util/docs.d.ts

@@ -0,0 +1,9 @@
+import type { Schema } from '../validation/schema.js';
+import type { SecurityScheme } from './security.js';
+/**
+ * Generate OpenAPI documentation for parameters.
+ * @param params - Record of parameters.
+ * @param position - The position of the parameter, e.g. `path`, `query`, `header`. This is passed directly to OpenAPI.
+ * @returns A list of parameter documentations in OpenAPI format.
+ */
+export declare const paramDocs: <Params extends Record<string, Schema<unknown>>>(params: Params, position: "path" | "query" | "header", security: SecurityScheme[]) => object[];

package/dist/src/util/docs.js

@@ -0,0 +1,57 @@
+/**
+ * Generate OpenAPI documentation for parameters.
+ * @param params - Record of parameters.
+ * @param position - The position of the parameter, e.g. `path`, `query`, `header`. This is passed directly to OpenAPI.
+ * @returns A list of parameter documentations in OpenAPI format.
+ */
+export const paramDocs = (params, position, security) => {
+    const result = [];
+    for (const name in params) {
+        if (isAuthToken(name, position, security)) {
+            // don't include auth tokens in the documentation, they're already
+            // handled by the separate authentication feature of OpenAPI
+            continue;
+        }
+        const docs = params[name].documentation();
+        result.push({
+            name,
+            in: position,
+            description: 'description' in docs ? docs.description : undefined,
+            required: !params[name].isOptional(),
+            schema: docs,
+        });
+    }
+    return result;
+};
+/**
+ * Check whether this parameter is an auth token, and should therefore not be
+ * included directly in the generated documentation.
+ * @param paramName - The name of the parameter to check.
+ * @param position - The position of the parameter.
+ * @param security - The security schemes that are enabled for this endpoint.
+ * @param securitySchemes - The security scheme definitions.
+ * @returns Whether the parameter is an auth token.
+ */
+const isAuthToken = (paramName, position, securitySchemes) => {
+    if (position === 'path') {
+        // path parameters cannot be auth tokens
+        return false;
+    }
+    for (const scheme of securitySchemes) {
+        if (scheme.scheme.type === 'http') {
+            if (paramName.toLowerCase() === 'authorization' &&
+                position === 'header') {
+                // http auth token has to be in authorization header
+                return true;
+            }
+        }
+        else {
+            if (scheme.scheme.in === position &&
+                paramName.toLowerCase() === scheme.scheme.name.toLowerCase()) {
+                // API key has to have the correct name and be in the correct position
+                return true;
+            }
+        }
+    }
+    return false;
+};

package/dist/src/util/security.d.ts

@@ -0,0 +1,14 @@
+export declare class SecurityScheme {
+    name: string;
+    scheme: SecuritySchemeData;
+    constructor(name: string, scheme: SecuritySchemeData);
+}
+type SecuritySchemeData = {
+    type: 'http';
+    scheme: 'basic' | 'bearer';
+} | {
+    type: 'apiKey';
+    in: 'header' | 'query' | 'cookie';
+    name: string;
+};
+export {};

package/dist/src/util/security.js

@@ -0,0 +1,6 @@
+export class SecurityScheme {
+    constructor(name, scheme) {
+        this.name = name;
+        this.scheme = scheme;
+    }
+}

package/dist/src/util/stream.d.ts

@@ -0,0 +1,2 @@
+import type { Readable } from 'node:stream';
+export declare const readableToBuffer: (stream: Readable) => Promise<Buffer<ArrayBuffer>>;

package/dist/src/util/stream.js

@@ -0,0 +1,7 @@
+export const readableToBuffer = async (stream) => {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+};

package/dist/src/validation/body.d.ts

@@ -0,0 +1,46 @@
+import type { Readable } from 'node:stream';
+/**
+ * The base class for all body types.
+ * @typeParam Provides - The type that is provided by this body type.
+ * When a parse is successful, this is the type of object you get back.
+ * @typeParam Accepts - The type that is accepted by this body type.
+ * When you want a parse to be successful, this is the type of object
+ * you have to pass in. This is always weaker than `Provides`, since you
+ * can always pass in a value of `Provides` and get a success.
+ */
+export declare abstract class BodyType<Provides, Accepts> {
+    _provides: Provides;
+    _accepts: Accepts;
+    constructor();
+    /**
+     * Deserialize a raw stream.
+     * @param stream - The raw stream.
+     * @param contentType - The content type.
+     */
+    abstract deserialize(stream: Readable, contentType: string): Promise<Provides>;
+    /**
+     * Generate OpenAPI docs for this body.
+     */
+    abstract bodyDocs(): object;
+}
+/**
+ * Get the type that is provided by a schema. When you parse
+ * something with a schema, this is the type you get back.
+ */
+export type TypeofProvides<T extends BodyType<unknown, unknown>> = T['_provides'];
+/**
+ * Get the type that is accepted by a schema. When you parse
+ * something with a schema, this is the type you have to pass
+ * in to get a successful result.
+ */
+export type TypeofAccepts<T extends BodyType<unknown, unknown>> = T['_accepts'];
+/**
+ * Get the type that is parsed by a schema. This is the same
+ * as `TypeofProvides`.
+ *
+ * ```typescript
+ * const schema = y.string();
+ * type SchemaType = y.Typeof<typeof schema>; // string
+ * ```
+ */
+export type Typeof<T extends BodyType<unknown, unknown>> = TypeofProvides<T>;

package/dist/src/validation/body.js

@@ -0,0 +1,15 @@
+/**
+ * The base class for all body types.
+ * @typeParam Provides - The type that is provided by this body type.
+ * When a parse is successful, this is the type of object you get back.
+ * @typeParam Accepts - The type that is accepted by this body type.
+ * When you want a parse to be successful, this is the type of object
+ * you have to pass in. This is always weaker than `Provides`, since you
+ * can always pass in a value of `Provides` and get a success.
+ */
+export class BodyType {
+    constructor() {
+        this._provides = undefined;
+        this._accepts = undefined;
+    }
+}

package/dist/src/validation/boolean.d.ts

@@ -0,0 +1,10 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class BooleanSchema extends ModifiableSchema<boolean> {
+    parse(obj: unknown): boolean;
+    documentation(): object;
+}
+/**
+ * A schema matching any boolean.
+ */
+export declare const boolean: () => BooleanSchema;
+export {};

package/dist/src/validation/boolean.js

@@ -0,0 +1,27 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class BooleanSchema extends ModifiableSchema {
+    parse(obj) {
+        if (obj === 'true') {
+            return true;
+        }
+        if (obj === 'false') {
+            return false;
+        }
+        if (typeof obj !== 'boolean') {
+            throw new ValidationError([
+                new Issue([], `Expected boolean but got ${typeof obj}`),
+            ]);
+        }
+        return obj;
+    }
+    documentation() {
+        return {
+            type: 'boolean',
+        };
+    }
+}
+/**
+ * A schema matching any boolean.
+ */
+export const boolean = () => new BooleanSchema();

package/dist/src/validation/date.d.ts

@@ -0,0 +1,11 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class DateSchema extends ModifiableSchema<Date> {
+    parse(obj: unknown): Date;
+    documentation(): object;
+}
+/**
+ * A schema matching date objects, or strings and numbers that can be
+ * interpreted as dates.
+ */
+export declare const date: () => DateSchema;
+export {};

package/dist/src/validation/date.js

@@ -0,0 +1,29 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class DateSchema extends ModifiableSchema {
+    parse(obj) {
+        if (obj instanceof Date) {
+            return obj;
+        }
+        if (typeof obj === 'string' || typeof obj === 'number') {
+            const date = new Date(obj);
+            if (date.toString() !== 'Invalid Date') {
+                return date;
+            }
+        }
+        throw new ValidationError([
+            new Issue([], `Expected date but got ${typeof obj}`),
+        ]);
+    }
+    documentation() {
+        return {
+            type: 'string',
+            format: 'date-time',
+        };
+    }
+}
+/**
+ * A schema matching date objects, or strings and numbers that can be
+ * interpreted as dates.
+ */
+export const date = () => new DateSchema();

package/dist/src/validation/doc.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from './schema.js';
+export declare class DocSchema<T> extends Schema<T> {
+    private readonly _schema;
+    private readonly _description;
+    private readonly _example?;
+    constructor(schema: Schema<T>, description: string, example?: T);
+    parse(obj: unknown): T;
+    documentation(): object;
+    isOptional(): boolean;
+}

package/dist/src/validation/doc.js

@@ -0,0 +1,22 @@
+import { Schema } from './schema.js';
+export class DocSchema extends Schema {
+    constructor(schema, description, example) {
+        super();
+        this._schema = schema;
+        this._description = description;
+        this._example = example;
+    }
+    parse(obj) {
+        return this._schema.parse(obj);
+    }
+    documentation() {
+        return {
+            description: this._description,
+            ...(this._example !== undefined && { example: this._example }),
+            ...this._schema.documentation(),
+        };
+    }
+    isOptional() {
+        return this._schema.isOptional();
+    }
+}

package/dist/src/validation/either.d.ts

@@ -0,0 +1,15 @@
+import type { Readable } from 'node:stream';
+import { BodyType, type Typeof, type TypeofAccepts, type TypeofProvides } from './body.js';
+declare class EitherBody<T extends [...BodyType<unknown, unknown>[]]> extends BodyType<TypeofProvides<T[number]>, TypeofAccepts<T[number]>> {
+    private options;
+    constructor(options: T);
+    deserialize(stream: Readable, contentType: string): Promise<Typeof<T[number]>>;
+    bodyDocs(): object;
+}
+/**
+ * A body that matches any of the provided options.
+ * @param options
+ * @returns
+ */
+export declare const either: <T extends [...BodyType<unknown, unknown>[]]>(...options: T) => EitherBody<T>;
+export {};

package/dist/src/validation/either.js

@@ -0,0 +1,38 @@
+import { BodyType, } from './body.js';
+import { ValidationError } from './error.js';
+class EitherBody extends BodyType {
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    deserialize(stream, contentType) {
+        const issues = [];
+        for (const option of this.options) {
+            try {
+                return option.deserialize(stream, contentType);
+            }
+            catch (error) {
+                if (error instanceof ValidationError) {
+                    issues.push(...error.issues);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        throw new ValidationError(issues);
+    }
+    bodyDocs() {
+        let docs = {};
+        for (const option of this.options) {
+            docs = { ...docs, ...option.bodyDocs() };
+        }
+        return docs;
+    }
+}
+/**
+ * A body that matches any of the provided options.
+ * @param options
+ * @returns
+ */
+export const either = (...options) => new EitherBody(options);

package/dist/src/validation/enum.d.ts

@@ -0,0 +1,19 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class EnumSchema<T extends [...(string | number)[]]> extends ModifiableSchema<T[number]> {
+    private readonly options;
+    private readonly normalized;
+    constructor(options: T);
+    parse(obj: unknown): T[number];
+    documentation(): object;
+}
+/**
+ * A schema that matches exactly the values provided. The options provided can
+ * be either strings or numbers.
+ *
+ * ```typescript
+ * const options = y.enum(3, 4, 'hello');
+ * type OptionsType = y.Typeof<typeof options>; // 3 | 4 | 'hello'
+ * ```
+ */
+export declare const _enum: <T extends [...(string | number)[]]>(...options: T) => EnumSchema<T>;
+export {};

package/dist/src/validation/enum.js

@@ -0,0 +1,44 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class EnumSchema extends ModifiableSchema {
+    constructor(options) {
+        super();
+        this.options = options;
+        this.normalized = options.map((option) => option.toString());
+    }
+    parse(obj) {
+        if (typeof obj !== 'string' && typeof obj !== 'number') {
+            // enum objects can only be strings or numbers
+            throw new ValidationError([
+                new Issue([], `Expected one of ${this.options.join(', ')} but got ${typeof obj}`),
+            ]);
+        }
+        // compare only the stringified (normalized) values
+        const normalizedObj = obj.toString();
+        const index = this.normalized.indexOf(normalizedObj);
+        if (index === -1) {
+            // invalid value
+            throw new ValidationError([
+                new Issue([], `Expected one of ${this.options.join(', ')} but got ${obj}`),
+            ]);
+        }
+        // return the un-normalized value
+        return this.options[index];
+    }
+    documentation() {
+        return {
+            type: 'string',
+            enum: this.options,
+        };
+    }
+}
+/**
+ * A schema that matches exactly the values provided. The options provided can
+ * be either strings or numbers.
+ *
+ * ```typescript
+ * const options = y.enum(3, 4, 'hello');
+ * type OptionsType = y.Typeof<typeof options>; // 3 | 4 | 'hello'
+ * ```
+ */
+export const _enum = (...options) => new EnumSchema(options);

package/dist/src/validation/error.d.ts

@@ -0,0 +1,21 @@
+export declare class Issue {
+    readonly path: string[];
+    readonly message: string;
+    constructor(path: string[], message: string);
+}
+export declare class ValidationError extends Error {
+    readonly issues: Issue[];
+    constructor(issues: Issue[]);
+    /**
+     * Format the validation error as a string.
+     * @returns The formatted error.
+     */
+    format(): string;
+    /**
+     * Adds a prefix to the validation error paths.
+     * @param prefix - The prefix path.
+     * @returns The prefixed error.
+     */
+    withPrefix(prefix: string): Issue[];
+    private static formatIssues;
+}

package/dist/src/validation/error.js

@@ -0,0 +1,32 @@
+export class Issue {
+    constructor(path, message) {
+        this.path = path;
+        this.message = message;
+    }
+}
+export class ValidationError extends Error {
+    constructor(issues) {
+        super(ValidationError.formatIssues(issues));
+        this.issues = issues;
+    }
+    /**
+     * Format the validation error as a string.
+     * @returns The formatted error.
+     */
+    format() {
+        return ValidationError.formatIssues(this.issues);
+    }
+    /**
+     * Adds a prefix to the validation error paths.
+     * @param prefix - The prefix path.
+     * @returns The prefixed error.
+     */
+    withPrefix(prefix) {
+        return this.issues.map((issue) => new Issue([prefix, ...issue.path], issue.message));
+    }
+    static formatIssues(issues) {
+        return issues
+            .map((issue) => `Error at \`${issue.path.join('.')}\`: ${issue.message}.`)
+            .join(' ');
+    }
+}

package/dist/src/validation/integer.d.ts

@@ -0,0 +1,23 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class IntegerSchema extends ModifiableSchema<number> {
+    private readonly minValue?;
+    private readonly maxValue?;
+    constructor(min?: number, max?: number);
+    /**
+     * Set the minimum value the number is allowed to be.
+     * @param value - The minimum value.
+     */
+    min(value: number): IntegerSchema;
+    /**
+     * Set the maximum value the number is allowed to be.
+     * @param value - The maximum value.
+     */
+    max(value: number): IntegerSchema;
+    parse(obj: unknown): number;
+    documentation(): object;
+}
+/**
+ * A schema that matches an integer.
+ */
+export declare const integer: () => IntegerSchema;
+export {};

package/dist/src/validation/integer.js

@@ -0,0 +1,64 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class IntegerSchema extends ModifiableSchema {
+    constructor(min, max) {
+        super();
+        this.minValue = min;
+        this.maxValue = max;
+    }
+    /**
+     * Set the minimum value the number is allowed to be.
+     * @param value - The minimum value.
+     */
+    min(value) {
+        if (!Number.isInteger(value)) {
+            throw new Error('minimum value has to be an integer');
+        }
+        return new IntegerSchema(value, this.maxValue);
+    }
+    /**
+     * Set the maximum value the number is allowed to be.
+     * @param value - The maximum value.
+     */
+    max(value) {
+        if (!Number.isInteger(value)) {
+            throw new Error('maximum value has to be an integer');
+        }
+        return new IntegerSchema(this.minValue, value);
+    }
+    parse(obj) {
+        if (typeof obj !== 'number' && typeof obj !== 'string') {
+            throw new ValidationError([
+                new Issue([], `Expected number but got ${typeof obj}`),
+            ]);
+        }
+        const num = typeof obj === 'number' ? obj : Number.parseFloat(obj);
+        if (Number.isNaN(num) || !Number.isInteger(num)) {
+            throw new ValidationError([
+                new Issue([], `Expected integer but got ${typeof obj}`),
+            ]);
+        }
+        if (this.minValue !== undefined && num < this.minValue) {
+            throw new ValidationError([
+                new Issue([], `Must be at least ${this.minValue}, but was ${num}`),
+            ]);
+        }
+        if (this.maxValue !== undefined && num > this.maxValue) {
+            throw new ValidationError([
+                new Issue([], `Must be at most ${this.maxValue}, but was ${num}`),
+            ]);
+        }
+        return num;
+    }
+    documentation() {
+        return {
+            type: 'integer',
+            ...(this.minValue !== undefined && { minimum: this.minValue }),
+            ...(this.maxValue !== undefined && { maximum: this.maxValue }),
+        };
+    }
+}
+/**
+ * A schema that matches an integer.
+ */
+export const integer = () => new IntegerSchema();

package/dist/src/validation/json.d.ts

@@ -0,0 +1,12 @@
+import type { Readable } from 'node:stream';
+import { BodyType } from './body.js';
+import type { Schema } from './schema.js';
+declare class JsonBody<T> extends BodyType<T, T> {
+    private contentType;
+    private schema;
+    constructor(contentType: string, schema: Schema<T>);
+    deserialize(stream: Readable, contentType: string): Promise<T>;
+    bodyDocs(): object;
+}
+export declare const json: <T>(schema: Schema<T>, contentType: string) => JsonBody<T>;
+export {};

package/dist/src/validation/json.js

@@ -0,0 +1,33 @@
+import { readableToBuffer } from '../util/stream.js';
+import { BodyType } from './body.js';
+import { Issue, ValidationError } from './error.js';
+class JsonBody extends BodyType {
+    constructor(contentType, schema) {
+        super();
+        this.contentType = contentType;
+        this.schema = schema;
+    }
+    async deserialize(stream, contentType) {
+        const buffer = await readableToBuffer(stream);
+        if (buffer.length === 0) {
+            return this.schema.parse({});
+        }
+        if (contentType !== this.contentType) {
+            throw new ValidationError([
+                new Issue([], `Expected content type \`${this.contentType}\`, but got \`${contentType}\``),
+            ]);
+        }
+        const obj = JSON.parse(buffer.toString('utf-8'));
+        return this.schema.parse(obj);
+    }
+    bodyDocs() {
+        return {
+            [this.contentType]: {
+                schema: this.schema.documentation(),
+            },
+        };
+    }
+}
+export const json = (schema, contentType) => {
+    return new JsonBody(contentType, schema);
+};