nervur 0.23.0 → 0.24.0

package/dist/being/need.d.ts

@@ -1,49 +0,0 @@
-import { type Schema } from './schema.ts';
-/** The three hints an ask or a method may carry. */
-export interface Hints {
-    readonly readOnly?: boolean;
-    readonly idempotent?: boolean;
-    readonly destructive?: boolean;
-}
-/** A method as its author writes it, in a need or in an ask's entry. */
-export interface MethodSpec {
-    readonly args?: Schema;
-    readonly result?: Schema;
-    readonly hints?: Hints;
-    readonly description?: string;
-    /** How long an awaited caller waits for it, in milliseconds, within the bound. */
-    readonly wait?: number;
-}
-/** A method of a blueprint, every field settled. */
-export interface BlueprintMethod {
-    readonly args: Schema;
-    readonly result?: Schema;
-    readonly hints: Required<Hints>;
-    readonly description?: string;
-    readonly wait: number;
-}
-/** An awaited call's wait where none is named, and the bound no wait passes. */
-export declare const WAIT = 30000;
-export declare const WAIT_BOUND = 300000;
-/** The shape of what can be called: a name and its methods. */
-export interface Blueprint {
-    readonly name: string;
-    readonly methods: Readonly<Record<string, BlueprintMethod>>;
-}
-export declare const BLUEPRINT: unique symbol;
-/** A need: her methods by name, and the blueprint they make. */
-export type Need<M extends Record<string, MethodSpec> = Record<string, MethodSpec>> = {
-    readonly [K in keyof M]: M[K];
-} & {
-    readonly [BLUEPRINT]: Blueprint;
-};
-/** Whether a method is awaited: `readOnly` implies `idempotent`. */
-export declare const awaited: (hints: Hints | undefined) => boolean;
-/** Hints settled, `readOnly` carrying `idempotent` with it. */
-export declare const settled: (hints: Hints | undefined) => Required<Hints>;
-/** One method settled: the empty object where args are omitted. */
-export declare const method: (spec: MethodSpec) => BlueprintMethod;
-/** A blueprint at its minimum, under the name matching uses. */
-export declare const need: <const M extends Record<string, MethodSpec>>(name: string, methods: M) => Need<M>;
-/** The blueprint a need makes, or nothing where the value is no need. */
-export declare const blueprintOf: (value: unknown) => Blueprint | undefined;

package/dist/being/need.js

@@ -1,33 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// A need: a blueprint at its minimum, the shape of what she calls.
-import { s } from './schema.js';
-/** An awaited call's wait where none is named, and the bound no wait passes. */
-export const WAIT = 30_000;
-export const WAIT_BOUND = 300_000;
-export const BLUEPRINT = Symbol('blueprint');
-/** Whether a method is awaited: `readOnly` implies `idempotent`. */
-export const awaited = (hints) => hints?.idempotent === true || hints?.readOnly === true;
-/** Hints settled, `readOnly` carrying `idempotent` with it. */
-export const settled = (hints) => ({
-    readOnly: hints?.readOnly === true,
-    idempotent: awaited(hints),
-    destructive: hints?.destructive === true,
-});
-/** One method settled: the empty object where args are omitted. */
-export const method = (spec) => Object.freeze({
-    args: spec.args ?? s.object({}),
-    ...(spec.result === undefined ? {} : { result: spec.result }),
-    hints: Object.freeze(settled(spec.hints)),
-    ...(spec.description === undefined ? {} : { description: spec.description }),
-    wait: typeof spec.wait === 'number' ? Math.min(spec.wait, WAIT_BOUND) : WAIT,
-});
-/** A blueprint at its minimum, under the name matching uses. */
-export const need = (name, methods) => {
-    const blueprint = Object.freeze({
-        name,
-        methods: Object.freeze(Object.fromEntries(Object.entries(methods).map(([key, spec]) => [key, method(spec)]))),
-    });
-    return Object.freeze({ ...methods, [BLUEPRINT]: blueprint });
-};
-/** The blueprint a need makes, or nothing where the value is no need. */
-export const blueprintOf = (value) => typeof value === 'object' && value !== null && BLUEPRINT in value ? value[BLUEPRINT] : undefined;

package/dist/being/schema.d.ts

@@ -1,100 +0,0 @@
-declare const TYPE: unique symbol;
-/** A schema in the closed subset, typed by what it admits. */
-export type Schema<T = unknown> = {
-    readonly [key: string]: unknown;
-} & {
-    readonly [TYPE]?: T;
-};
-/** The type a schema admits. */
-export type Infer<S> = S extends {
-    readonly [TYPE]?: infer T;
-} ? T : never;
-/** A relation crossing: a handle on the way out, a standing id on the way in. */
-export interface HandleMark {
-    readonly handleMark: true;
-}
-/** An invitation carried unopened. It is an object and never a value. */
-export interface Invitation {
-    readonly invitation: true;
-}
-/** A reference to one of her asks, or to an occupant she minted. */
-export interface Handle {
-    readonly id: string;
-}
-type Mapped<T, H> = T extends HandleMark ? H : T extends Invitation ? // A handle under s.invitation leaves as an invitation too.
-Invitation | (H extends Handle ? Handle : never) : T extends Uint8Array ? T : T extends readonly (infer E)[] ? Mapped<E, H>[] : T extends object ? {
-    [K in keyof T]: Mapped<T[K], H>;
-} : T;
-/** What a method receives: a handle has arrived as a standing id. */
-export type Inbound<T> = Mapped<T, string>;
-/** What a call sends: a handle leaves as a handle, or as an invitation she carries, for its receiver to take. */
-export type Outbound<T> = Mapped<T, Handle | Invitation>;
-export declare const HANDLE_MEDIA = "application/vnd.nervur.handle";
-export declare const INVITATION_MEDIA = "application/vnd.nervur.invitation";
-/** The keywords the house checks, and no other. */
-export declare const KEYWORDS: ReadonlySet<string>;
-declare const OPTIONAL: unique symbol;
-type Optional<S extends Schema> = S & {
-    readonly [OPTIONAL]: true;
-};
-type Flat<T> = {
-    [K in keyof T]: T[K];
-} & {};
-type Props = Record<string, Schema>;
-type OptionalKeys<P extends Props> = {
-    [K in keyof P]: P[K] extends {
-        readonly [OPTIONAL]: true;
-    } ? K : never;
-}[keyof P];
-type ObjectOf<P extends Props> = Flat<{
-    -readonly [K in Exclude<keyof P, OptionalKeys<P>>]: Infer<P[K]>;
-} & {
-    -readonly [K in OptionalKeys<P>]?: Infer<P[K]>;
-}>;
-/** A method of a need, as `s.reply` reads it. */
-export interface MethodRef<R = unknown> {
-    readonly args?: Schema;
-    readonly result?: Schema<R>;
-}
-/** The args of a reply: the method's result, or its error. */
-export type Reply<R> = {
-    result: R;
-    error?: undefined;
-} | {
-    error: {
-        message: string;
-    };
-    result?: undefined;
-};
-type Bounds = {
-    minimum?: number;
-    maximum?: number;
-};
-type Lengths = {
-    minLength?: number;
-    maxLength?: number;
-};
-type Scalar = string | number | boolean | null;
-export declare const s: Readonly<{
-    object: <P extends Props>(properties: P) => Schema<ObjectOf<P>>;
-    string: (lengths?: Lengths & {
-        pattern?: string;
-    }) => Schema<string>;
-    number: (bounds?: Bounds) => Schema<number>;
-    integer: (bounds?: Bounds) => Schema<number>;
-    boolean: () => Schema<boolean>;
-    array: <S extends Schema>(items: S) => Schema<Infer<S>[]>;
-    enum: <const V extends readonly Scalar[]>(values: V) => Schema<V[number]>;
-    const: <const V extends Scalar>(value: V) => Schema<V>;
-    bytes: (lengths?: Lengths) => Schema<Uint8Array>;
-    optional: <S extends Schema>(schema: S) => Optional<S>;
-    handle: () => Schema<HandleMark>;
-    invitation: () => Schema<Invitation>;
-    reply: <R>(method: MethodRef<R>) => Schema<Reply<unknown extends R ? null : R>>;
-}>;
-/**
- * Every way a schema leaves the subset, each as a sentence naming where.
- * The empty list is a schema the house checks.
- */
-export declare const outside: (schema: unknown, at?: string) => string[];
-export {};

package/dist/being/schema.js

@@ -1,132 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The schema builder. Each call writes JSON Schema 2020-12 in the closed
-// subset the house checks, and carries the TypeScript type beside it.
-export const HANDLE_MEDIA = 'application/vnd.nervur.handle';
-export const INVITATION_MEDIA = 'application/vnd.nervur.invitation';
-/** The keywords the house checks, and no other. */
-export const KEYWORDS = new Set([
-    'type',
-    'properties',
-    'required',
-    'additionalProperties',
-    'enum',
-    'const',
-    'items',
-    'minLength',
-    'maxLength',
-    'minimum',
-    'maximum',
-    'pattern',
-    'anyOf',
-    'contentEncoding',
-    'contentMediaType',
-]);
-const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
-const OPTIONAL = Symbol('optional');
-const frozen = (schema) => Object.freeze(schema);
-const bounded = (schema, bounds = {}) => {
-    for (const [key, value] of Object.entries(bounds))
-        if (value !== undefined)
-            Object.assign(schema, { [key]: value });
-    return schema;
-};
-export const s = Object.freeze({
-    object: (properties) => {
-        const required = Object.keys(properties).filter((key) => !(OPTIONAL in properties[key]));
-        const plain = Object.fromEntries(Object.entries(properties).map(([key, value]) => [key, strip(value)]));
-        return frozen({ type: 'object', properties: Object.freeze(plain), required: Object.freeze(required), additionalProperties: false });
-    },
-    string: (lengths) => frozen(bounded({ type: 'string' }, lengths)),
-    number: (bounds) => frozen(bounded({ type: 'number' }, bounds)),
-    integer: (bounds) => frozen(bounded({ type: 'integer' }, bounds)),
-    boolean: () => frozen({ type: 'boolean' }),
-    array: (items) => frozen({ type: 'array', items: strip(items) }),
-    enum: (values) => frozen({ enum: Object.freeze([...values]) }),
-    const: (value) => frozen({ const: value }),
-    // Lengths count bytes, and the schema counts their hex, two digits a byte.
-    bytes: (lengths) => frozen(bounded({ type: 'string', contentEncoding: 'base16' }, { minLength: lengths?.minLength === undefined ? undefined : lengths.minLength * 2, maxLength: lengths?.maxLength === undefined ? undefined : lengths.maxLength * 2 })),
-    optional: (schema) => Object.freeze({ ...schema, [OPTIONAL]: true }),
-    handle: () => frozen({ type: 'string', contentEncoding: 'base16', contentMediaType: HANDLE_MEDIA }),
-    invitation: () => frozen({ type: 'string', contentEncoding: 'base16', contentMediaType: INVITATION_MEDIA }),
-    reply: (method) => frozen({
-        anyOf: Object.freeze([
-            s.object({ result: method.result ?? s.const(null) }),
-            s.object({ error: s.object({ message: s.string() }) }),
-        ]),
-    }),
-});
-const strip = (schema) => {
-    if (!(OPTIONAL in schema))
-        return schema;
-    const { [OPTIONAL]: _mark, ...plain } = schema;
-    return frozen(plain);
-};
-/**
- * Every way a schema leaves the subset, each as a sentence naming where.
- * The empty list is a schema the house checks.
- */
-export const outside = (schema, at = 'the schema') => {
-    if (typeof schema !== 'object' || schema === null || Array.isArray(schema))
-        return [`${at} is not a schema object`];
-    const found = [];
-    const node = schema;
-    for (const key of Object.keys(node))
-        if (!KEYWORDS.has(key))
-            found.push(`${at} names ${key}, outside the subset`);
-    const type = node.type;
-    if (type !== undefined && !(typeof type === 'string' && TYPES.has(type)))
-        found.push(`${at} has a type the subset does not name`);
-    if (node.contentEncoding !== undefined && node.contentEncoding !== 'base16')
-        found.push(`${at} has a contentEncoding other than base16`);
-    const media = node.contentMediaType;
-    if (media !== undefined && media !== HANDLE_MEDIA && media !== INVITATION_MEDIA)
-        found.push(`${at} has a contentMediaType that is not a mark`);
-    if (media !== undefined && node.contentEncoding !== 'base16')
-        found.push(`${at} marks a relation that is not base16`);
-    for (const key of ['minLength', 'maxLength']) {
-        const value = node[key];
-        if (value !== undefined && !(Number.isInteger(value) && value >= 0))
-            found.push(`${at} has a ${key} that is not a count`);
-    }
-    for (const key of ['minimum', 'maximum']) {
-        if (node[key] !== undefined && !Number.isFinite(node[key]))
-            found.push(`${at} has a ${key} that is not a number`);
-    }
-    if (node.pattern !== undefined)
-        found.push(...pattern(node.pattern, at));
-    if (node.properties !== undefined) {
-        if (typeof node.properties !== 'object' || node.properties === null || Array.isArray(node.properties))
-            found.push(`${at} has properties that are not an object`);
-        else
-            for (const [key, value] of Object.entries(node.properties))
-                found.push(...outside(value, `${at}.${key}`));
-    }
-    if (node.required !== undefined && !(Array.isArray(node.required) && node.required.every((key) => typeof key === 'string')))
-        found.push(`${at} has required that is not a list of names`);
-    if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean')
-        found.push(`${at} has additionalProperties that is not true or false`);
-    if (node.enum !== undefined && !(Array.isArray(node.enum) && node.enum.every(scalar)))
-        found.push(`${at} has an enum that is not a list of scalars`);
-    if ('const' in node && !scalar(node.const))
-        found.push(`${at} has a const that is not a scalar`);
-    if (node.items !== undefined)
-        found.push(...outside(node.items, `${at}[]`));
-    if (node.anyOf !== undefined) {
-        if (!Array.isArray(node.anyOf) || node.anyOf.length === 0)
-            found.push(`${at} has an anyOf that is not a list of schemas`);
-        else
-            node.anyOf.forEach((branch, index) => found.push(...outside(branch, `${at}|${index}`)));
-    }
-    return found;
-};
-const scalar = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
-const pattern = (value, at) => {
-    if (typeof value !== 'string')
-        return [`${at} has a pattern that is not a string`];
-    try {
-        return RegExp(value, 'u').unicode ? [] : [`${at} has a pattern that is not unicode`];
-    }
-    catch {
-        return [`${at} has a pattern that does not compile`];
-    }
-};

package/dist/being/table.d.ts

@@ -1,48 +0,0 @@
-import { type Json, type Me } from './being.ts';
-import { type Blueprint, type BlueprintMethod } from './need.ts';
-/** The roles the house names. */
-export declare const HOUSE_ROLES: ReadonlySet<string>;
-/** The state of a class that names none. */
-export declare const READY = "ready";
-/** An ask's entry, settled. `null` is the entry's omission. */
-export interface TableEntry extends BlueprintMethod {
-    readonly method: string;
-    /** Where the ask exists; `null`, every state. */
-    readonly in: readonly string[] | null;
-    /** Who may call it; `null`, every occupant but handles. */
-    readonly for: readonly string[] | null;
-    /** Where it may land; `null`, the state it began in. */
-    readonly to: readonly string[] | null;
-    /** Its author wrote `idempotent: false`, which a public being's default needs to know. */
-    readonly effect: boolean;
-    readonly examples: readonly Json[];
-}
-/** A class as the house reads her. */
-export interface Table {
-    readonly kind: string;
-    readonly description?: string;
-    readonly view?: string;
-    readonly cells: Readonly<Record<string, Json>>;
-    readonly needs: Readonly<Record<string, Blueprint>>;
-    readonly roles: Readonly<Record<string, (asker: never, me: never) => boolean>>;
-    readonly state: (me: Me<Record<string, Json>>) => string;
-    /** The state of her default cells. */
-    readonly first: string;
-    readonly states: readonly string[];
-    readonly asks: Readonly<Record<string, TableEntry>>;
-}
-/** A class the house will not resolve, and every reason why. */
-export declare class Refused extends Error {
-    readonly reasons: readonly string[];
-    constructor(what: string, reasons: readonly string[]);
-}
-/** Whether a value is JSON, as cells and notes hold. */
-export declare const isJson: (value: unknown) => value is Json;
-/**
- * An offer's blueprint as it arrives, from a need or from a program's
- * describe, held to the rules a need is: a keyword outside the subset,
- * or a field that is none, refuses it where it arrives.
- */
-export declare const offered: (value: unknown, where?: string) => Blueprint;
-/** Her class checked and settled, or refused with every reason. */
-export declare const resolve: (Class: unknown) => Table;