ocel 0.0.1-alpha.1 → 0.0.1

package/dist/build-env.d.ts

@@ -0,0 +1,17 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export declare class BuildEnvError extends Error {
+    name: string;
+}
+export type BuildEnv<TSchemas extends Record<string, StandardSchemaV1>> = {
+    readonly [K in keyof TSchemas]: StandardSchemaV1.InferOutput<TSchemas[K]>;
+};
+/**
+ * Declares the environment the config itself needs while it is being evaluated
+ * — values read from the shell or the project's `.env` — and validates them
+ * before they reach provider options, so a missing or malformed value fails at
+ * the config rather than mid-deploy.
+ *
+ * Anything returned here can end up in deployment records. A real secret
+ * belongs in the runtime `secret` env class instead.
+ */
+export declare function buildEnv<const TSchemas extends Record<string, StandardSchemaV1>>(schemas: TSchemas): BuildEnv<TSchemas>;

package/dist/build-env.js

@@ -0,0 +1,41 @@
+import { isUsableKey } from "./env/definition.js";
+import { parse } from "./env/standard.js";
+export class BuildEnvError extends Error {
+    name = "BuildEnvError";
+}
+/**
+ * Declares the environment the config itself needs while it is being evaluated
+ * — values read from the shell or the project's `.env` — and validates them
+ * before they reach provider options, so a missing or malformed value fails at
+ * the config rather than mid-deploy.
+ *
+ * Anything returned here can end up in deployment records. A real secret
+ * belongs in the runtime `secret` env class instead.
+ */
+export function buildEnv(schemas) {
+    for (const key of Object.keys(schemas)) {
+        if (!isUsableKey(key)) {
+            throw new BuildEnvError(`'${key}' is not a usable variable name: use upper-case letters, digits and underscores, starting with a letter or underscore.`);
+        }
+    }
+    const resolved = new Map();
+    return new Proxy({}, {
+        get(_target, property) {
+            if (typeof property === "symbol")
+                return undefined;
+            const key = property;
+            const schema = schemas[key];
+            if (!schema) {
+                throw new BuildEnvError(`'${key}' is not declared in the buildEnv call. Add it there before reading it.`);
+            }
+            if (resolved.has(key))
+                return resolved.get(key);
+            const result = parse(schema, process.env[key]);
+            if (!result.ok) {
+                throw new BuildEnvError(`'${key}' ${result.message} — set it in your shell or in the project's .env`);
+            }
+            resolved.set(key, result.value);
+            return result.value;
+        },
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+export { type BuildEnv, BuildEnvError, buildEnv } from "./build-env.js";
+export type { AppConfig, AppDomainConfig, AwsProviderOptions, BuildConfig, DevEnvSourceDescriptor, DiscoveryConfig, DNSDescriptor, EdgeDescriptor, EnvSourceConfig, EnvSourceDescriptor, ExecOptions, GcpProviderOptions, HealthConfig, InfisicalOptions, OcelConfig, ProjectDomainConfig, ProviderDescriptor, RegistryConfig, VpsProviderOptions, VpsTarget, } from "./generated/config.js";
+import type { OcelConfig } from "./generated/config.js";
+/**
+ * Something an app needs of wherever it is served. A need listed in
+ * `allowDegraded` is waived, and the deploy proceeds without it; an unwaived
+ * need the deploy cannot meet refuses the deploy instead of silently serving
+ * less than the app asks for.
+ */
+export type Need = NonNullable<OcelConfig["allowDegraded"]>[number];
+/** What an app runs on. */
+export type Compute = NonNullable<AppComputeOf<OcelConfig>>;
+type AppComputeOf<T> = T extends {
+    apps?: (infer A)[];
+} ? A extends {
+    compute?: infer C;
+} ? C : never : never;
+/** What a serverless app is built with. */
+export type Framework = NonNullable<AppFrameworkOf<OcelConfig>>;
+type AppFrameworkOf<T> = T extends {
+    apps?: (infer A)[];
+} ? A extends {
+    framework?: infer F;
+} ? F : never : never;
+/**
+ * Declares a project. The object it takes is the same document `ocel.json`
+ * contains, so a TypeScript config is an authoring surface over data and nothing
+ * more: nothing in it is evaluated at deploy time.
+ */
+export declare function defineConfig(config: OcelConfig): OcelConfig;

package/dist/config.js

@@ -0,0 +1,9 @@
+export { BuildEnvError, buildEnv } from "./build-env.js";
+/**
+ * Declares a project. The object it takes is the same document `ocel.json`
+ * contains, so a TypeScript config is an authoring surface over data and nothing
+ * more: nothing in it is evaluated at deploy time.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/declaration/callsite.d.ts

@@ -0,0 +1,15 @@
+interface Site {
+    file: string;
+    line: number;
+}
+/**
+ * The file and line of the innermost frame outside this package and outside
+ * `node_modules` — the user code whose call reached the SDK. Undefined when the
+ * stack names no such frame.
+ */
+export declare function callSite(): Site | undefined;
+/** The {@link callSite} as `file:line`, or `""`. */
+export declare function declarationSite(): string;
+/** The file of the {@link callSite}, or `""`. */
+export declare function callSiteFile(): string;
+export {};

package/dist/declaration/callsite.js

@@ -0,0 +1,43 @@
+const frameRE = /\(?((?:\/|file:|[A-Za-z]:\\)[^()]+?):(\d+):\d+\)?$/;
+function parseFrame(frame) {
+    const at = frameRE.exec(frame.trim());
+    if (!at?.[1] || !at[2])
+        return undefined;
+    return { file: at[1].replace(/^file:\/\//, ""), line: Number(at[2]) };
+}
+function parentOf(file) {
+    return file.slice(0, Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\")));
+}
+function isUnder(file, dir) {
+    return dir !== "" && (file.startsWith(`${dir}/`) || file.startsWith(`${dir}\\`));
+}
+/**
+ * The file and line of the innermost frame outside this package and outside
+ * `node_modules` — the user code whose call reached the SDK. Undefined when the
+ * stack names no such frame.
+ */
+export function callSite() {
+    let ownRoot;
+    for (const frame of (new Error().stack ?? "").split("\n").slice(1)) {
+        const site = parseFrame(frame);
+        if (!site)
+            continue;
+        if (ownRoot === undefined) {
+            ownRoot = parentOf(parentOf(site.file));
+            continue;
+        }
+        if (isUnder(site.file, ownRoot) || /[/\\]node_modules[/\\]/.test(site.file))
+            continue;
+        return site;
+    }
+    return undefined;
+}
+/** The {@link callSite} as `file:line`, or `""`. */
+export function declarationSite() {
+    const site = callSite();
+    return site ? `${site.file}:${site.line}` : "";
+}
+/** The file of the {@link callSite}, or `""`. */
+export function callSiteFile() {
+    return callSite()?.file ?? "";
+}

package/dist/declaration/component.d.ts

@@ -0,0 +1,4 @@
+/** A declared resource, identified by the id the dev server registers it under. */
+export interface Component {
+    __id(): string;
+}

package/dist/declaration/component.js

@@ -0,0 +1 @@
+export {};

package/dist/declaration/defer.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var __ocelRegister: Promise<unknown>[];
+}
+/** Holds a registration with the dev server until the app's declarations are collected. Throws when no dev server is running. */
+export declare function defer(p: Promise<any>): void;

package/dist/declaration/defer.js

@@ -0,0 +1,9 @@
+import { OCEL_DEV_SERVER } from "../runtime/dev-server.js";
+/** Holds a registration with the dev server until the app's declarations are collected. Throws when no dev server is running. */
+export function defer(p) {
+    if (!OCEL_DEV_SERVER) {
+        throw new Error("OCEL_DEV_SERVER environment variable is not set");
+    }
+    globalThis.__ocelRegister ??= [];
+    globalThis.__ocelRegister.push(p);
+}

package/dist/delivery/duration.d.ts

@@ -0,0 +1,13 @@
+import { type Timestamp } from "@bufbuild/protobuf/wkt";
+/**
+ * A length of time: a number of seconds, or a string such as `"500ms"`, `"30s"`, `"5m"`,
+ * `"2h"` or `"1d"`.
+ */
+export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+export declare function parseDurationMilliseconds(duration: Duration): number;
+export interface DurationFields {
+    seconds: bigint;
+    nanos: number;
+}
+export declare function encodeDuration(duration: Duration | undefined): DurationFields | undefined;
+export declare function encodeDueAt(delay: Duration | Date | undefined): Timestamp | undefined;

package/dist/delivery/duration.js

@@ -0,0 +1,36 @@
+import { timestampFromMs } from "@bufbuild/protobuf/wkt";
+const millisecondsPerUnit = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+const durationPattern = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+export function parseDurationMilliseconds(duration) {
+    if (typeof duration === "number") {
+        if (!Number.isFinite(duration) || duration < 0) {
+            throw new Error(`a duration is a non-negative number of seconds, not ${duration}`);
+        }
+        return duration * 1_000;
+    }
+    const match = durationPattern.exec(duration);
+    if (!match?.[1] || !match[2]) {
+        throw new Error(`"${duration}" is not a duration: write a number of seconds, or a string such as "500ms", "30s", "5m", "2h" or "1d"`);
+    }
+    return Number(match[1]) * millisecondsPerUnit[match[2]];
+}
+export function encodeDuration(duration) {
+    if (duration === undefined)
+        return undefined;
+    const milliseconds = Math.round(parseDurationMilliseconds(duration));
+    return {
+        seconds: BigInt(Math.floor(milliseconds / 1_000)),
+        nanos: (milliseconds % 1_000) * 1_000_000,
+    };
+}
+export function encodeDueAt(delay) {
+    if (delay === undefined)
+        return undefined;
+    return timestampFromMs(delay instanceof Date ? delay.getTime() : Date.now() + parseDurationMilliseconds(delay));
+}

package/dist/delivery/lane.d.ts

@@ -0,0 +1,4 @@
+import { Lane as ProtoLane } from "../gen/proto/app/topic/v1/topic_pb.js";
+/** The lane a message waits in: `high`, `default` and `low` are read in a 6:3:1 ratio. */
+export type Lane = "high" | "default" | "low";
+export declare function encodeLane(lane: Lane | undefined): ProtoLane;

package/dist/delivery/lane.js

@@ -0,0 +1,15 @@
+import { Lane as ProtoLane } from "../gen/proto/app/topic/v1/topic_pb.js";
+const protoLanes = {
+    high: ProtoLane.HIGH,
+    default: ProtoLane.DEFAULT,
+    low: ProtoLane.LOW,
+};
+export function encodeLane(lane) {
+    if (lane === undefined)
+        return ProtoLane.UNSPECIFIED;
+    const value = protoLanes[lane];
+    if (value === undefined) {
+        throw new Error(`"${lane}" is not a lane: use "high", "default" or "low"`);
+    }
+    return value;
+}

package/dist/delivery/payload.d.ts

@@ -0,0 +1,6 @@
+/** The most bytes of JSON a payload may take. */
+export declare const PAYLOAD_LIMIT_BYTES = 262144;
+/** A payload's JSON text as bytes, with `undefined` sent as `null`. Throws over {@link PAYLOAD_LIMIT_BYTES}. */
+export declare function encodePayload(payload: unknown): Uint8Array;
+/** The value JSON text holds; `null` when there is no text. */
+export declare function decodeJson(bytes: Uint8Array): unknown;

package/dist/delivery/payload.js

@@ -0,0 +1,14 @@
+/** The most bytes of JSON a payload may take. */
+export const PAYLOAD_LIMIT_BYTES = 262_144;
+/** A payload's JSON text as bytes, with `undefined` sent as `null`. Throws over {@link PAYLOAD_LIMIT_BYTES}. */
+export function encodePayload(payload) {
+    const bytes = new TextEncoder().encode(JSON.stringify(payload ?? null));
+    if (bytes.byteLength > PAYLOAD_LIMIT_BYTES) {
+        throw new Error(`a payload is at most ${PAYLOAD_LIMIT_BYTES} bytes (256 KiB) of JSON, and this one is ${bytes.byteLength} bytes`);
+    }
+    return bytes;
+}
+/** The value JSON text holds; `null` when there is no text. */
+export function decodeJson(bytes) {
+    return bytes.byteLength > 0 ? JSON.parse(new TextDecoder().decode(bytes)) : null;
+}

package/dist/delivery/retry.d.ts

@@ -0,0 +1,16 @@
+import { type Duration, type DurationFields } from "./duration.js";
+/** How a failed attempt is retried. */
+export interface RetryOptions {
+    /** Attempts made before the run fails, the first included. */
+    maxAttempts?: number;
+    /** The backoff before the first retry. */
+    minDelay?: Duration;
+    /** The longest backoff between two attempts. */
+    maxDelay?: Duration;
+}
+export interface RetryPolicyFields {
+    maxAttempts: number;
+    minDelay: DurationFields | undefined;
+    maxDelay: DurationFields | undefined;
+}
+export declare function encodeRetryPolicy(retry: RetryOptions | undefined): RetryPolicyFields | undefined;

package/dist/delivery/retry.js

@@ -0,0 +1,10 @@
+import { encodeDuration } from "./duration.js";
+export function encodeRetryPolicy(retry) {
+    if (retry === undefined)
+        return undefined;
+    return {
+        maxAttempts: retry.maxAttempts ?? 0,
+        minDelay: encodeDuration(retry.minDelay),
+        maxDelay: encodeDuration(retry.maxDelay),
+    };
+}

package/dist/delivery/schema.d.ts

@@ -0,0 +1,10 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export declare function encodeJsonSchema(schema: StandardSchemaV1 | undefined): string;
+export type Validation = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function validatePayload(schema: StandardSchemaV1, payload: unknown): Promise<Validation>;

package/dist/delivery/schema.js

@@ -0,0 +1,20 @@
+import { describeIssues } from "../env/standard.js";
+export function encodeJsonSchema(schema) {
+    const converter = schema?.["~standard"]
+        ?.jsonSchema;
+    if (!converter)
+        return "";
+    try {
+        return JSON.stringify(converter.input({ target: "draft-2020-12" }));
+    }
+    catch {
+        return "";
+    }
+}
+export async function validatePayload(schema, payload) {
+    const result = await schema["~standard"].validate(payload);
+    if (result.issues) {
+        return { ok: false, message: describeIssues(result.issues) };
+    }
+    return { ok: true, value: result.value };
+}

package/dist/dns.d.ts

@@ -0,0 +1,11 @@
+import type { DNSDescriptor } from "./config.js";
+/** Options for Cloudflare DNS. */
+export interface CloudflareDnsOptions {
+    /**
+     * The zone the records are written into. Omit it and ocel picks the zone
+     * that covers the hostname.
+     */
+    zone?: string;
+}
+/** Declares Cloudflare as the DNS the project's records are written into. */
+export declare function cloudflareDns(options?: CloudflareDnsOptions): DNSDescriptor;

package/dist/dns.js

@@ -0,0 +1,4 @@
+/** Declares Cloudflare as the DNS the project's records are written into. */
+export function cloudflareDns(options = {}) {
+    return { cloudflare: options };
+}

package/dist/edge.d.ts

@@ -0,0 +1,4 @@
+import type { CloudflareEdgeOptions, EdgeDescriptor } from "./generated/config.js";
+export type { CloudflareEdgeOptions } from "./generated/config.js";
+/** Declares Cloudflare as the edge the project's hostnames are served from. */
+export declare function cloudflare(options?: CloudflareEdgeOptions): EdgeDescriptor;

package/dist/edge.js

@@ -0,0 +1,4 @@
+/** Declares Cloudflare as the edge the project's hostnames are served from. */
+export function cloudflare(options = {}) {
+    return { cloudflare: options };
+}

package/dist/env/access.d.ts

@@ -0,0 +1,22 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { EnvDefinitions, GroupDefinition, VariableDefinition } from "./definition.js";
+type EnvValue<T> = T extends GroupDefinition<infer TDefinitions, infer TOptional> ? Env<TDefinitions> | (TOptional extends true ? undefined : never) : T extends VariableDefinition ? T["schema"] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T["schema"]> : string : never;
+/** The object a `defineEnv` call hands back: one property per declared variable or group. */
+export type Env<TDefinitions extends EnvDefinitions> = {
+    readonly [K in keyof TDefinitions]: EnvValue<TDefinitions[K]>;
+};
+/** What a tier supplies so the shared accessor can read its variables. */
+export interface Access {
+    resolve(key: string, definition: VariableDefinition): unknown;
+    delivered(key: string, definition: VariableDefinition): boolean;
+    generationOf(definition: VariableDefinition): number;
+}
+export declare const FIXED = -1;
+/**
+ * The generation of a value nothing marks the freshness of, which is read
+ * again on every access. It is `NaN`, so it equals no generation — its own
+ * included — and `Math.max` passes it on to a group containing such a member.
+ */
+export declare const UNCACHED: number;
+export declare function envAccessor<TDefinitions extends EnvDefinitions>(definitions: TDefinitions, access: Access): Env<TDefinitions>;
+export {};

package/dist/env/access.js

@@ -0,0 +1,49 @@
+import { undeclared } from "./value.js";
+export const FIXED = -1;
+/**
+ * The generation of a value nothing marks the freshness of, which is read
+ * again on every access. It is `NaN`, so it equals no generation — its own
+ * included — and `Math.max` passes it on to a group containing such a member.
+ */
+export const UNCACHED = Number.NaN;
+export function envAccessor(definitions, access) {
+    const resolved = new Map();
+    return new Proxy({}, {
+        get(_target, property) {
+            if (typeof property === "symbol")
+                return undefined;
+            const key = property;
+            const definition = definitions[key];
+            if (!definition)
+                throw undeclared(key);
+            const generation = generationOf(definition, access);
+            const memo = resolved.get(key);
+            if (memo?.generation === generation)
+                return memo.value;
+            const value = "definitions" in definition
+                ? resolveGroup(definition, access)
+                : access.resolve(key, definition);
+            resolved.set(key, { generation, value });
+            return value;
+        },
+    });
+}
+function generationOf(definition, access) {
+    if (!("definitions" in definition))
+        return access.generationOf(definition);
+    let generation = FIXED;
+    for (const member of Object.values(definition.definitions)) {
+        generation = Math.max(generation, access.generationOf(member));
+    }
+    return generation;
+}
+function resolveGroup(definition, access) {
+    const members = Object.entries(definition.definitions);
+    if (definition.optional && !members.some(([key, member]) => access.delivered(key, member))) {
+        return undefined;
+    }
+    const value = {};
+    for (const [key, member] of members)
+        value[key] = access.resolve(key, member);
+    return value;
+}

package/dist/env/client.d.ts

@@ -0,0 +1,5 @@
+export type ClientEnv = Readonly<Record<string, string | undefined>>;
+export declare class EnvClientError extends Error {
+    name: string;
+}
+export declare const clientEnv: ClientEnv;

package/dist/env/client.js

@@ -0,0 +1,10 @@
+export class EnvClientError extends Error {
+    name = "EnvClientError";
+}
+export const clientEnv = new Proxy({}, {
+    get(_target, property) {
+        if (typeof property === "symbol")
+            return undefined;
+        throw new EnvClientError(`'${property}' cannot be read: 'ocel/env/client' resolved to its unresolved fallback, because no client accessor is mapped for this app. Run \`ocel dev\` or \`ocel deploy\`: each writes the app's own 'env-client.ts' under the project's '.ocel' directory and points 'ocel/env/client' at it from the app's tsconfig.json or jsconfig.json, one of which the app must have for the mapping to be stated. Where that config is one ocel cannot write the entry into, the command refuses and names the entry to add by hand.`);
+    },
+});

package/dist/env/declare.d.ts

@@ -0,0 +1,2 @@
+import { type FlatDefinitions } from "./definition.js";
+export declare function declareEnv(definitions: FlatDefinitions, source: string, schemaSource: string): Promise<void>;

package/dist/env/declare.js

@@ -0,0 +1,83 @@
+import { VariableProblem_Kind, VariableClass as WireClass, } from "../gen/proto/app/resources/v1/variables_pb.js";
+import { rpc } from "../runtime/rpc.js";
+import { complaint, isRequired, } from "./definition.js";
+import { parse } from "./standard.js";
+const WIRE_CLASS = {
+    plain: WireClass.PLAIN,
+    sensitive: WireClass.SENSITIVE,
+    secret: WireClass.SECRET,
+};
+export async function declareEnv(definitions, source, schemaSource) {
+    const groups = Object.values(Object.entries(definitions).reduce((all, [, definition]) => {
+        if (definition.group) {
+            all[definition.group] = {
+                key: definition.group,
+                required: !definition.groupOptional,
+                description: definition.groupDescription ?? "",
+            };
+        }
+        return all;
+    }, {}));
+    const { cells } = await rpc.resource.declareEnv({
+        definitions: Object.entries(definitions).map(([key, definition]) => ({
+            key,
+            class: WIRE_CLASS[definition.class],
+            clientAccessible: definition.client === true,
+            required: isRequired(definition),
+            folders: [...(definition.folders ?? [])],
+            source,
+            schemaSource,
+            hasSchema: definition.schema !== undefined,
+            ...(definition.description === undefined ? {} : { description: definition.description }),
+            ...(definition.group === undefined ? {} : { group: definition.group }),
+        })),
+        groups,
+    });
+    const problems = validate(definitions, cells);
+    if (problems.length > 0) {
+        await rpc.resource.reportEnvProblems({ problems });
+    }
+}
+function validate(definitions, cells) {
+    const problems = [];
+    for (const [key, definition] of Object.entries(definitions)) {
+        const stored = cells.filter((c) => c.key === key);
+        if (isRequired(definition)) {
+            for (const folder of requiredFolders(definition)) {
+                if (definition.groupOptional &&
+                    definition.group &&
+                    !switchedOn(definitions, cells, definition.group, folder))
+                    continue;
+                if (!stored.some((c) => c.folder === folder)) {
+                    problems.push(problem(key, folder, VariableProblem_Kind.MISSING, ""));
+                }
+            }
+        }
+        if (definition.class === "secret" || !definition.schema)
+            continue;
+        for (const cell of stored) {
+            const result = parse(definition.schema, cell.value);
+            if (!result.ok) {
+                problems.push(problem(key, cell.folder, VariableProblem_Kind.INVALID, complaint(definition, result.message)));
+            }
+        }
+    }
+    return problems;
+}
+function switchedOn(definitions, cells, group, folder) {
+    return Object.entries(definitions).some(([key, definition]) => definition.group === group && hasCell(cells, key, definition, folder));
+}
+function hasCell(cells, key, definition, folder) {
+    const at = (where) => cells.some((cell) => cell.key === key && cell.folder === where);
+    const scope = definition.folders ?? [];
+    if (scope.length > 0) {
+        return folder !== "" && scope.includes(folder) && at(folder);
+    }
+    return (folder !== "" && at(folder)) || at("");
+}
+function requiredFolders(definition) {
+    return definition.folders?.length ? definition.folders : [""];
+}
+function problem(key, folder, kind, detail) {
+    return { key, folder, kind, detail };
+}

package/dist/env/definition.d.ts

@@ -0,0 +1,46 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type VariableClass = "plain" | "sensitive" | "secret";
+export type ConfidentialClass = Exclude<VariableClass, "plain">;
+interface VariableOptions<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    schema?: TSchema;
+    folders?: readonly string[];
+    description?: string;
+}
+export type VariableDefinition<TSchema extends StandardSchemaV1 = StandardSchemaV1> = (VariableOptions<TSchema> & {
+    class: "plain";
+    client?: boolean;
+}) | (VariableOptions<TSchema> & {
+    class: ConfidentialClass;
+    client?: false;
+});
+export interface GroupOptions {
+    readonly optional?: boolean;
+    readonly description?: string;
+}
+export interface GroupDefinition<TDefinitions extends Definitions = Definitions, TOptional extends boolean = boolean> {
+    readonly definitions: TDefinitions;
+    readonly optional: TOptional;
+    readonly description?: string;
+}
+type IsOptional<TOptions extends GroupOptions> = TOptions["optional"] extends true ? true : false;
+export type Definitions = Record<string, VariableDefinition>;
+export type EnvDefinitions = Record<string, VariableDefinition | GroupDefinition>;
+export type FlatDefinition = VariableDefinition & {
+    readonly group?: string;
+    readonly groupOptional?: boolean;
+    readonly groupDescription?: string;
+};
+export type FlatDefinitions = Record<string, FlatDefinition>;
+/** A set of variables an app takes together: every member is reached through the group and
+ * nowhere else, and `{ optional: true }` reads the whole group as `undefined` until a value
+ * is delivered for one of its members. */
+export declare function group<const TDefinitions extends Definitions, const TOptions extends GroupOptions = GroupOptions>(definitions: TDefinitions, options?: TOptions): GroupDefinition<TDefinitions, IsOptional<TOptions>>;
+export declare function flattenDefinitions(definitions: EnvDefinitions): FlatDefinitions;
+export declare function isLive(definition: VariableDefinition): boolean;
+export declare const URL_KEY = "OCEL_URL";
+export declare const CLIENT_URL_KEY = "NEXT_PUBLIC_OCEL_URL";
+export declare function isUsableKey(key: string): boolean;
+export declare function validateDefinitions(definitions: EnvDefinitions, source: string): FlatDefinitions;
+export declare function isRequired(definition: VariableDefinition): boolean;
+export declare function complaint(definition: VariableDefinition, message: string): string;
+export {};