@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1723

package/schema-BF-Y1EVu.mjs

@@ -0,0 +1,142 @@
+//#region src/database/schema.ts
+/** A table's name: a leading `_` is the Database's own. */
+const TABLE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u;
+const v = Object.freeze({
+	string: () => "string",
+	number: () => "number",
+	boolean: () => "boolean",
+	/** Any JSON value, at any depth. */
+	document: () => "document",
+	/** May be left out or null. */
+	optional: (shape) => ({ optional: shape }),
+	array: (shape) => ({ array: shape }),
+	object: (fields) => ({ object: fields }),
+	int64: () => "int64",
+	bytes: () => "bytes",
+	timestamp: () => "timestamp",
+	decimal: () => "decimal",
+	literal: (value) => ({ literal: value }),
+	union: (...shapes) => ({ union: shapes }),
+	record: (shape) => ({ record: shape }),
+	id: (table) => ({ id: String(table) })
+});
+const INDEX = /^[A-Za-z][A-Za-z0-9_]{0,63}$/u;
+const INDEX_FIELDS = 8;
+const RESERVED_INDEXES = /* @__PURE__ */ new Set(["by_id", "by_creation_time"]);
+/** Whether an index may order a field of this shape: what the Database orders, its keys comparing as their values do. */
+function orderable(shape) {
+	const inner = shape && typeof shape === "object" && "optional" in shape ? shape.optional : shape;
+	if (typeof inner === "string") return [
+		"string",
+		"number",
+		"boolean",
+		"int64",
+		"timestamp"
+	].includes(inner);
+	if (!inner) return false;
+	if ("id" in inner) return true;
+	if ("literal" in inner) return [
+		"string",
+		"number",
+		"boolean"
+	].includes(typeof inner.literal);
+	if ("union" in inner) return inner.union.every(orderable);
+	return false;
+}
+function tableOf(fields, indexes) {
+	return Object.freeze({
+		fields,
+		indexes,
+		index(name, field, { unique = false } = {}) {
+			if (typeof name !== "string" || !INDEX.test(name) || RESERVED_INDEXES.has(name)) throw new TypeError(`index ${JSON.stringify(name)}: a name of [A-Za-z][A-Za-z0-9_]{0,63}, not by_id or by_creation_time`);
+			if (name in indexes) throw new TypeError(`index ${name}: declared twice`);
+			const list = Array.isArray(field) ? field : [field];
+			if (!list.length || list.length > INDEX_FIELDS || new Set(list).size !== list.length) throw new TypeError(`index ${name}: a field, or a list of up to ${INDEX_FIELDS} different fields`);
+			for (const one of list) {
+				if (typeof one !== "string" || !(one in fields)) throw new TypeError(`index ${name}: ${JSON.stringify(one)} is not a field of the table`);
+				if (!orderable(fields[one])) throw new TypeError(`index ${name}: ${one} is not a string, number or boolean`);
+			}
+			const on = list.length === 1 ? list[0] : Object.freeze([...list]);
+			return tableOf(fields, Object.freeze({
+				...indexes,
+				[name]: unique ? Object.freeze({
+					fields: on,
+					unique: true
+				}) : on
+			}));
+		},
+		searchIndex(name) {
+			throw new TypeError(`searchIndex ${JSON.stringify(name)}: not available yet`);
+		},
+		vectorIndex(name) {
+			throw new TypeError(`vectorIndex ${JSON.stringify(name)}: not available yet`);
+		}
+	});
+}
+/** An index's fields in order. */
+function indexFields(declared) {
+	const fields = declared !== null && typeof declared === "object" && !Array.isArray(declared) ? declared.fields : declared;
+	return Array.isArray(fields) ? [...fields] : [fields];
+}
+function defineTable(fields) {
+	if (fields === null || typeof fields !== "object" || Array.isArray(fields)) throw new TypeError("defineTable({ <field>: v.<shape>() })");
+	for (const [field, shape] of Object.entries(fields)) {
+		if (field.startsWith("_")) throw new TypeError(`defineTable: ${field}: a leading _ is the Database's`);
+		if (shapeError(shape, void 0, field)?.endsWith("not a shape")) throw new TypeError(`defineTable: ${field}: not a shape`);
+	}
+	return tableOf(Object.freeze({ ...fields }), Object.freeze({}));
+}
+function defineSchema(tables) {
+	if (tables === null || typeof tables !== "object" || Array.isArray(tables)) throw new TypeError("defineSchema({ <table>: defineTable(...) })");
+	const out = {};
+	const indexes = {};
+	for (const [name, table] of Object.entries(tables)) {
+		if (!TABLE.test(name)) throw new TypeError(`defineSchema: "${name}" is not a table name`);
+		if (!table?.fields) throw new TypeError(`defineSchema: "${name}" is not a defineTable(...)`);
+		out[name] = table.fields;
+		indexes[name] = table.indexes ?? Object.freeze({});
+	}
+	return Object.freeze({
+		schema: true,
+		tables: Object.freeze(out),
+		indexes: Object.freeze(indexes)
+	});
+}
+/** Whether `value` fits `shape`: null, or the reason. An id is a non-empty string. */
+function shapeError(shape, value, at = "the value") {
+	const wrong = (what) => `${at}: ${what} expected`;
+	if (shape === "document") return null;
+	if (typeof shape === "string") switch (shape) {
+		case "string": return typeof value === "string" ? null : wrong("a string");
+		case "number": return typeof value === "number" && Number.isFinite(value) ? null : wrong("a number");
+		case "boolean": return typeof value === "boolean" ? null : wrong("a boolean");
+		case "int64": return Number.isSafeInteger(value) || typeof value === "string" && /^-?\d{1,19}$/u.test(value) ? null : wrong("a whole number of 64 bits");
+		case "bytes": return typeof value === "string" && /^[A-Za-z0-9+/=_-]*$/u.test(value) ? null : wrong("bytes as base64");
+		case "timestamp": return typeof value === "number" && Number.isFinite(value) ? null : wrong("a timestamp (milliseconds)");
+		case "decimal": return typeof value === "string" && /^-?\d+(\.\d+)?$/u.test(value) ? null : wrong("a decimal as a string");
+		default: return `${at}: no shape ${String(shape)}`;
+	}
+	if (shape && typeof shape === "object") {
+		if ("optional" in shape) return value === void 0 || value === null ? null : shapeError(shape.optional, value, at);
+		if ("array" in shape) return Array.isArray(value) ? value.map((item, k) => shapeError(shape.array, item, `${at}[${k}]`)).find(Boolean) ?? null : wrong("an array");
+		if ("object" in shape) {
+			if (value === null || typeof value !== "object" || Array.isArray(value)) return wrong("an object");
+			const record = value;
+			for (const key of Object.keys(record)) if (!(key in shape.object)) return `${at}.${key}: no such field`;
+			for (const [key, inner] of Object.entries(shape.object)) {
+				if (record[key] === void 0 && inner && typeof inner === "object" && "optional" in inner) continue;
+				if (record[key] === void 0) return `${at}.${key}: missing`;
+				const why = shapeError(inner, record[key], `${at}.${key}`);
+				if (why) return why;
+			}
+			return null;
+		}
+		if ("literal" in shape) return JSON.stringify(value) === JSON.stringify(shape.literal) ? null : wrong(`the value ${JSON.stringify(shape.literal)}`);
+		if ("union" in shape) return shape.union.some((one) => shapeError(one, value, at) === null) ? null : wrong("one of the union's shapes");
+		if ("record" in shape) return value !== null && typeof value === "object" && !Array.isArray(value) ? Object.entries(value).map(([k, item]) => shapeError(shape.record, item, `${at}.${k}`)).find(Boolean) ?? null : wrong("an object");
+		if ("id" in shape) return typeof value === "string" && value.length > 0 && value.length <= 256 ? null : wrong(`an id of ${shape.id}`);
+	}
+	return `${at}: not a shape`;
+}
+//#endregion
+export { shapeError as a, indexFields as i, defineSchema as n, v as o, defineTable as r, TABLE as t };

package/schema-DS8x1Dn8.mjs

@@ -0,0 +1,115 @@
+import { z } from "zod";
+//#region src/vector/errors.ts
+const vectorErrorCodes = [
+	"invalid",
+	"not_found",
+	"conflict",
+	"forbidden",
+	"unavailable"
+];
+var VectorError = class extends Error {
+	code;
+	constructor(code, why) {
+		super(why);
+		this.code = code;
+		this.name = "VectorError";
+	}
+};
+//#endregion
+//#region src/vector/schema.ts
+/**
+* What Vector DB accepts, as zod schemas: the client checks a call with them before it leaves the
+* caller, and `serve` checks every frame with them again, because a frame comes from the network.
+* A limit lives here once, so both edges hold the same one.
+*/
+/** Most numbers a Vector holds. */
+const MAX_DIMENSION = 4096;
+/** Most Vectors one upsert takes, and most ids one fetch or delete names. */
+const MAX_BATCH = 1e3;
+/** The most matches one query returns. */
+const MAX_TOP_K = 100;
+/** Most characters a text to embed has. */
+const MAX_TEXT = 3e4;
+/** Most bytes a Vector's metadata takes, as JSON. */
+const MAX_METADATA_BYTES = 10240;
+/** 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit. */
+const NamespaceName = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/, "a Vector namespace's name is 1 to 63 lowercase letters, digits and hyphens, starting with a letter or digit");
+/** How closeness is measured, fixed when a Vector namespace is made. */
+const Metric = z.enum([
+	"cosine",
+	"euclidean",
+	"dot"
+]);
+const Dimension = z.number().int().min(1).max(MAX_DIMENSION);
+const VectorId = z.string().min(1).max(512);
+const Scalar = z.union([
+	z.string().max(2048),
+	z.number().refine(Number.isFinite, "a number in metadata is finite"),
+	z.boolean()
+]);
+const FieldName = z.string().min(1).max(64).refine((name) => !name.startsWith("$") && !name.includes("."), "a metadata field's name does not start with $ or hold a dot");
+const Metadata = z.record(FieldName, Scalar).refine((metadata) => new TextEncoder().encode(JSON.stringify(metadata)).length <= MAX_METADATA_BYTES, `metadata is at most ${MAX_METADATA_BYTES} bytes as JSON`);
+/**
+* The largest value a Vector holds. Engines keep values and scores as 32-bit floats, and within it
+* every score of 4,096 values is one, finite: a squared distance is at most 4,096 · (2e17)², about
+* 1.6e38, under a 32-bit float's 3.4e38. Scores are exact to a 32-bit float's precision for values
+* from 1e-17 up.
+*/
+const MAX_VALUE = 0x16345785d8a0000;
+const Values = z.array(z.number().refine((value) => Number.isFinite(value) && Math.abs(value) <= 0x16345785d8a0000, `a Vector's values are finite numbers of at most ${MAX_VALUE} in size`)).min(1).max(MAX_DIMENSION);
+const Vector = z.object({
+	id: VectorId,
+	values: Values,
+	metadata: Metadata.optional()
+}).strict();
+const Text = z.string().max(MAX_TEXT).refine((text) => text.trim().length > 0, "a text to embed is not empty or all spaces");
+const TextVector = z.object({
+	id: VectorId,
+	text: Text,
+	metadata: Metadata.optional()
+}).strict();
+const Vectors = z.array(z.union([Vector, TextVector])).min(1).max(MAX_BATCH).refine((vectors) => new Set(vectors.map((v) => v.id)).size === vectors.length, "each id is upserted once a call");
+const Ids = z.array(VectorId).min(1).max(MAX_BATCH);
+const Bound = z.union([z.string().max(2048), z.number().refine(Number.isFinite)]);
+const Condition = z.union([Scalar, z.object({
+	$eq: Scalar.optional(),
+	$ne: Scalar.optional(),
+	$in: z.array(Scalar).min(1).max(100).optional(),
+	$nin: z.array(Scalar).min(1).max(100).optional(),
+	$gt: Bound.optional(),
+	$gte: Bound.optional(),
+	$lt: Bound.optional(),
+	$lte: Bound.optional()
+}).strict().refine((condition) => Object.keys(condition).length > 0, "a condition names an operator")]);
+/** Each field's condition, all of which must hold. A bare value is `$eq`. */
+const Filter = z.record(FieldName, Condition).refine((filter) => Object.keys(filter).length <= 20, "a filter names at most 20 fields");
+const QueryOptions = {
+	topK: z.number().int().min(1).max(100),
+	filter: Filter.optional(),
+	includeValues: z.boolean(),
+	includeMetadata: z.boolean(),
+	consistency: z.enum(["strong", "eventual"]).optional()
+};
+const Query = z.union([z.object({
+	vector: Values,
+	...QueryOptions
+}).strict(), z.object({
+	text: Text,
+	...QueryOptions
+}).strict()]);
+/** An embedding model's name, as the platform offers it. */
+const EmbeddingModel = z.string().min(1).max(100);
+const Settings = z.object({
+	dimension: Dimension,
+	metric: Metric,
+	embed: EmbeddingModel.optional()
+}).strict();
+/** `value` as `schema` reads it, or `invalid` with why not. */
+function checked(schema, value) {
+	const parsed = schema.safeParse(value);
+	if (parsed.success) return parsed.data;
+	const issue = parsed.error.issues[0];
+	throw new VectorError("invalid", `${issue && issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue?.message ?? "not valid"}`);
+}
+//#endregion
+export { MAX_TEXT as a, NamespaceName as c, Vectors as d, checked as f, MAX_METADATA_BYTES as i, Query as l, vectorErrorCodes as m, MAX_BATCH as n, MAX_TOP_K as o, VectorError as p, MAX_DIMENSION as r, MAX_VALUE as s, Ids as t, Settings as u };

package/schema-f7E9uzUn.d.mts

@@ -0,0 +1,74 @@
+//#region src/database/schema.d.ts
+/**
+ * A Database's shapes: `v`, `defineTable`, `defineSchema`, and the check of a value against a
+ * shape. Plain data and pure functions, the same as the engine's, so a schema built here is the one
+ * the Database builds.
+ *
+ *   export default defineSchema({
+ *     messages: defineTable({ channel: v.string(), body: v.string() }).index("by_channel", "channel"),
+ *   })
+ */
+/** A shape, as `v` makes it: a name for the simple ones, an object for the rest. */
+type Shape = "string" | "number" | "boolean" | "document" | "int64" | "bytes" | "timestamp" | "decimal" | {
+  readonly optional: Shape;
+} | {
+  readonly array: Shape;
+} | {
+  readonly object: Readonly<Record<string, Shape>>;
+} | {
+  readonly literal: unknown;
+} | {
+  readonly union: ReadonlyArray<Shape>;
+} | {
+  readonly record: Shape;
+} | {
+  readonly id: string;
+};
+declare const v: Readonly<{
+  string: () => Shape;
+  number: () => Shape;
+  boolean: () => Shape;
+  /** Any JSON value, at any depth. */
+  document: () => Shape;
+  /** May be left out or null. */
+  optional: (shape: Shape) => Shape;
+  array: (shape: Shape) => Shape;
+  object: (fields: Record<string, Shape>) => Shape;
+  int64: () => Shape;
+  bytes: () => Shape;
+  timestamp: () => Shape;
+  decimal: () => Shape;
+  literal: (value: string | number | boolean) => Shape;
+  union: (...shapes: Shape[]) => Shape;
+  record: (shape: Shape) => Shape;
+  id: (table: string) => Shape;
+}>;
+/** An index as declared: one field, a list of them for a compound index, or either with `unique`. */
+type IndexDeclaration = string | ReadonlyArray<string> | {
+  readonly fields: string | ReadonlyArray<string>;
+  readonly unique: true;
+};
+interface Table {
+  readonly fields: Readonly<Record<string, Shape>>;
+  readonly indexes: Readonly<Record<string, IndexDeclaration>>;
+  /** A new table with the index added: one field, or a list for a compound index; `{ unique: true }` lets no two rows share its key. */
+  index(name: string, field: string | ReadonlyArray<string>, options?: {
+    readonly unique?: boolean;
+  }): Table;
+  searchIndex(name: string): never;
+  vectorIndex(name: string): never;
+}
+interface Schema {
+  readonly schema: true;
+  readonly tables: Readonly<Record<string, Readonly<Record<string, Shape>>>>;
+  /** Every table's indexes, by name; a table with none has `{}`. */
+  readonly indexes: Readonly<Record<string, Readonly<Record<string, IndexDeclaration>>>>;
+}
+/** An index's fields in order. */
+declare function indexFields(declared: IndexDeclaration): string[];
+declare function defineTable(fields: Record<string, Shape>): Table;
+declare function defineSchema(tables: Record<string, Table>): Schema;
+/** Whether `value` fits `shape`: null, or the reason. An id is a non-empty string. */
+declare function shapeError(shape: Shape, value: unknown, at?: string): string | null;
+//#endregion
+export { defineSchema as a, shapeError as c, Table as i, v as l, Schema as n, defineTable as o, Shape as r, indexFields as s, IndexDeclaration as t };

package/server-C7O7CICU.d.mts

@@ -0,0 +1,182 @@
+import { r as Shape } from "./schema-f7E9uzUn.mjs";
+//#region src/database/server.d.ts
+/** A row as the Database keeps it: its fields, and its own `_`-fields. */
+type Row = Readonly<Record<string, unknown>>;
+/** A row as a function reads it. */
+type Document = Readonly<Record<string, unknown>> & {
+  readonly _id: string;
+  readonly _version: number;
+};
+/** A range's bounds on an index's first field, its order, and at most `limit` rows. */
+interface RangeOptions {
+  readonly eq?: unknown;
+  readonly gte?: unknown;
+  readonly gt?: unknown;
+  readonly lte?: unknown;
+  readonly lt?: unknown;
+  readonly order?: "asc" | "desc";
+  readonly limit?: number;
+}
+/** A scheduled run, as `ctx.scheduler.status` returns it. */
+interface ScheduledRun {
+  readonly name: string;
+  readonly args: unknown;
+  readonly at: number;
+  readonly state: string;
+  readonly error?: string;
+}
+/**
+ * What a Database gives a query or mutation to run against: its rows, the caller and the call. The
+ * Stand-in is one such; the Database's engine is another. Every read returns at once.
+ */
+interface Rows {
+  get(table: string, id: string): Row | null;
+  set(table: string, id: string, fields: Row): void;
+  delete(table: string, id: string): void;
+  /** The rows of `index` ("_id" for the table's order) within the bounds, each with its `_id`. Bounds are lists, one value for each of the index's leading fields. */
+  range(table: string, index: string, options: {
+    readonly eq?: ReadonlyArray<unknown>;
+    readonly gte?: unknown;
+    readonly gt?: unknown;
+    readonly lte?: unknown;
+    readonly lt?: unknown;
+    readonly order?: "asc" | "desc";
+    readonly limit: number;
+  }): ReadonlyArray<Row & {
+    readonly _id: string;
+  }>;
+  /** The call's own time. */
+  readonly now: number;
+  /** The signed-in caller, by the Project's sign-in's subject; null for none. */
+  readonly user: string | null;
+  /** Whether the Project's own server code, or the Database itself, is the caller. */
+  readonly server: boolean;
+  /** The sign-in provider the Database trusts, when it trusts exactly one. */
+  readonly issuer?: string | null;
+  /** The call's identity: a mutation's inserted ids come from it, so a run again makes the same ids. */
+  readonly call?: string | null;
+  /** Whether another function is the caller, which may call internal ones. */
+  readonly internal?: boolean;
+  /** The tables the schema declares, by field; none: every write is admitted. */
+  readonly schema?: Readonly<Record<string, Readonly<Record<string, Shape>>>> | null;
+  runAfter(ms: number, name: string, args: unknown): string;
+  scheduledRow(id: string): {
+    readonly name: string;
+    readonly args?: unknown;
+    readonly due: number;
+    readonly state: string;
+    readonly error?: string;
+  } | null;
+  cancelScheduled(id: string): boolean;
+}
+/** What a Database gives an action: reads that may wait, the network, and the other functions. */
+interface Capabilities {
+  get(table: string, id: string): Promise<Row | null>;
+  range(table: string, index: string, options: Parameters<Rows["range"]>[2]): Promise<ReadonlyArray<Row & {
+    readonly _id: string;
+  }>>;
+  readonly user: string | null;
+  readonly server: boolean;
+  readonly issuer?: string | null;
+  readonly internal?: boolean;
+  fetch(url: URL, init?: RequestInit): Promise<Response>;
+  now(): number;
+  random(bytes: number): Uint8Array;
+  run(name: string, args: unknown): Promise<unknown>;
+  schedule(ms: number, name: string, args: unknown): Promise<string>;
+  scheduled(id: string): Promise<ScheduledRun | null>;
+  cancel(id: string): Promise<boolean>;
+}
+type FunctionKind = "query" | "mutation" | "action";
+/** A function as defined: its name (none until it is exported under one), what runs it, and its options. */
+interface RegisteredFunction {
+  readonly name: string | null;
+  readonly handler: (on: Rows & Capabilities, args: unknown) => unknown;
+  readonly options: {
+    readonly kind: FunctionKind;
+    readonly args: {
+      readonly object: Readonly<Record<string, Shape>>;
+    } | null;
+    readonly returns: Shape | null;
+    readonly internal: boolean;
+    readonly cron: string | null;
+  };
+}
+/** A function's reference, as `api.<file>.<export>` holds it: its name and kind. */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind> {
+  readonly name: string;
+  readonly kind: Kind;
+}
+declare const OPERATOR: unique symbol;
+interface Operator {
+  readonly [OPERATOR]: "increment" | "take" | "give";
+  readonly n: number;
+}
+/** A field's value plus `n` (a field not yet there counts as 0). */
+declare const increment: (n?: number) => Operator;
+/** A field's value minus `n`; below zero the whole mutation fails with `InsufficientError` and writes nothing. */
+declare const take: (n?: number) => Operator;
+/** A field's value plus `n`: the inverse of `take`. */
+declare const give: (n?: number) => Operator;
+/** A `take` asked for more than the field holds: the mutation wrote nothing. */
+declare class InsufficientError extends Error {
+  readonly detail: {
+    readonly table: string;
+    readonly id: string;
+    readonly field: string;
+    readonly has: number;
+    readonly asked: number;
+  };
+  constructor(detail: {
+    readonly table: string;
+    readonly id: string;
+    readonly field: string;
+    readonly has: number;
+    readonly asked: number;
+  });
+}
+/** A mutation patched or replaced a row that is not there. */
+declare class NotFoundError extends Error {
+  readonly detail: {
+    readonly table: string;
+    readonly id: string;
+  };
+  constructor(detail: {
+    readonly table: string;
+    readonly id: string;
+  });
+}
+/** A call the Database refused: `why` is its reason, as the client's `DatabaseError` carries it. */
+declare class Refusal extends Error {
+  readonly why: string;
+  readonly detail?: unknown;
+  constructor(why: string, message: string, detail?: unknown);
+}
+type Definition = {
+  readonly args?: Record<string, Shape>;
+  readonly returns?: Shape;
+  readonly cron?: string;
+  readonly handler: (ctx: any, args: any) => unknown;
+};
+/** A function that reads rows and never writes them: `export const list = query({ args, returns, handler: (ctx, args) => ... })`. */
+declare function query(name: string | Definition, given?: Definition, extra?: {
+  internal?: boolean;
+}): RegisteredFunction;
+/** One serializable transaction: `export const send = mutation({ args, returns, handler: (ctx, args) => ... })`. */
+declare function mutation(name: string | Definition, given?: Definition, extra?: {
+  internal?: boolean;
+}): RegisteredFunction;
+/** May wait on the network: `export const charge = action({ args, returns, handler: async (ctx, args) => ... })`. */
+declare function action(name: string | Definition, given?: Definition, extra?: {
+  internal?: boolean;
+}): RegisteredFunction;
+/** As `query`, callable only by another function, never a client. */
+declare const internalQuery: (name: string | Definition, given?: Definition) => RegisteredFunction;
+/** As `mutation`, callable only by another function, never a client. */
+declare const internalMutation: (name: string | Definition, given?: Definition) => RegisteredFunction;
+/** As `action`, callable only by another function, never a client. */
+declare const internalAction: (name: string | Definition, given?: Definition) => RegisteredFunction;
+/** Whether a value is a function defined here, as a module of `db/` exports it. */
+declare const isFunction: (value: unknown) => value is RegisteredFunction;
+//#endregion
+export { take as C, query as S, internalAction as _, InsufficientError as a, isFunction as b, RangeOptions as c, Row as d, Rows as f, increment as g, give as h, FunctionReference as i, Refusal as l, action as m, Document as n, NotFoundError as o, ScheduledRun as p, FunctionKind as r, Operator as s, Capabilities as t, RegisteredFunction as u, internalMutation as v, mutation as x, internalQuery as y };

package/socket.d.mts

@@ -0,0 +1,67 @@
+import { m as StorageEngine } from "./index-sgdyoA2P.mjs";
+import { S3Credential } from "./s3.mjs";
+import { Transport } from "./wire.mjs";
+//#region src/socket.d.ts
+declare function sign(secret: string, challenge: string): Promise<string>;
+declare function sameHex(a: string, b: string): boolean;
+/** The browser's WebSocket, or one with the same shape. */
+type SocketLike = {
+  binaryType: string;
+  readonly readyState: number;
+  send(data: string | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  addEventListener(type: "close" | "error", listener: () => void): void;
+};
+/**
+ * A transport over WebSockets to `url` (`connections` of them, 16 when not given), each call sent on
+ * the one with the fewest calls in flight: one connection is one invocation on the server, so a few
+ * carry more at once. Each opens on its first call and again after it closes. A call in flight when its
+ * connection drops (a server going away on deploy closes every connection) is sent again on a new one
+ * when the wire says repeating it is safe (`repeatable`), and is otherwise `unavailable`, since it may
+ * have been carried out. Where no connection opens, or the runtime has no WebSocket, calls go over
+ * `fallback` for a minute, then a connection is tried again; without one they are `unavailable`.
+ */
+declare function socket(url: string, options: {
+  readonly key: string;
+  readonly secret: string;
+  readonly connections?: number;
+  readonly fallback?: Transport;
+  readonly WebSocket?: new (url: string) => SocketLike;
+  readonly clock?: () => number;
+}): Transport & {
+  close(): void;
+};
+/**
+ * `engine` as a Storage Key reaches it: its Buckets by name (every Bucket, under its own name, when it
+ * names none), reading always, writing only with `write` access and while the Bucket's writes are not
+ * paused. Metering is the platform's, never a key's.
+ */
+declare function keyed(engine: StorageEngine, credential: Omit<S3Credential, "secret">): StorageEngine;
+/**
+ * One connection's server side: send `greeting` first, then pass each message to `receive` and send
+ * what it returns. After `life` milliseconds send `closing`, and close once `idle` resolves.
+ */
+interface SocketSession {
+  readonly greeting: string;
+  readonly closing: string;
+  /** How long the connection may live, in milliseconds. */
+  readonly life: number;
+  /** Whether the connection has carried as many calls as one should, and should close as at the end of its life. */
+  spent(): boolean;
+  /** After `closing` is sent: resolves once every frame received has had its reply. */
+  idle(): Promise<void>;
+  /** The answer to a message: text during the handshake, a tagged frame after; null for none. */
+  receive(message: unknown): Promise<string | Uint8Array | null>;
+  /** Settles once the key is accepted or refused; a refused connection should then be closed. */
+  readonly settled: Promise<"ready" | "refused">;
+}
+/** A server's side of one connection: the handshake against `credentials`, then each frame served by `engine` as the key reaches it. */
+declare function socketSession(options: {
+  readonly engine: StorageEngine;
+  readonly credentials: (accessKeyId: string) => S3Credential | null | Promise<S3Credential | null>;
+}): SocketSession;
+//#endregion
+export { SocketSession, keyed, sameHex, sign, socket, socketSession };