@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/storage/properties.ts

@@ -0,0 +1,31 @@
+import { isFrozenData } from "../core/data.js";
+import type { ItemTypeDefinition, PropertyDefinition } from "./types.js";
+
+const propertiesByType = new WeakMap<ItemTypeDefinition, ReadonlyMap<string, PropertyDefinition>>();
+
+/** Only validated immutable definitions can retain an index across calls. */
+export function propertyFor(
+    definition: ItemTypeDefinition,
+    name: string,
+): PropertyDefinition | undefined {
+    if (!isFrozenData(definition)) {
+        return definition.properties.find((property) => property.name === name);
+    }
+
+    let indexed = propertiesByType.get(definition);
+
+    if (!indexed) {
+        const properties = new Map<string, PropertyDefinition>();
+
+        for (const property of definition.properties) {
+            if (!properties.has(property.name)) {
+                properties.set(property.name, property);
+            }
+        }
+
+        indexed = properties;
+        propertiesByType.set(definition, indexed);
+    }
+
+    return indexed.get(name);
+}

package/src/storage/sqlite/catalog.ts

@@ -0,0 +1,89 @@
+import type { CatalogEntry } from "../types.js";
+import { decodeAttributes, decodeProperties, decodeSource } from "./metadata.js";
+
+export interface CatalogRow {
+    readonly id: string;
+    readonly type: string;
+    readonly properties: string;
+    readonly attributes: string;
+    readonly source: string;
+}
+
+const selectionsMax = 64;
+
+/** Cache decoded rows privately; every reader still receives detached records. */
+export class CatalogEntries {
+    private readonly entries = new Map<string, { row: CatalogRow; entry: CatalogEntry }>();
+    private readonly selections = new Map<string | undefined, readonly CatalogRow[]>();
+    private epoch: number | undefined;
+
+    select(
+        type: string | undefined,
+        epoch: number | undefined,
+        read: () => readonly CatalogRow[],
+    ): readonly CatalogEntry[] {
+        this.refresh(epoch);
+        let rows = this.selections.get(type);
+
+        if (!rows) {
+            rows = read();
+
+            if (epoch !== undefined) {
+                if (this.selections.size >= selectionsMax) {
+                    this.selections.clear();
+                }
+
+                this.selections.set(type, rows);
+            }
+        }
+
+        return rows.map((row) => this.read(row, epoch));
+    }
+
+    read(row: CatalogRow, epoch: number | undefined): CatalogEntry {
+        this.refresh(epoch);
+        const key = JSON.stringify([row.type, row.id]);
+        let cached = this.entries.get(key);
+
+        if (
+            !cached ||
+            cached.row.properties !== row.properties ||
+            cached.row.attributes !== row.attributes ||
+            cached.row.source !== row.source
+        ) {
+            cached = {
+                row,
+                entry: {
+                    type: row.type,
+                    id: row.id,
+                    properties: decodeProperties(row.properties),
+                    attributes: decodeAttributes(row.attributes),
+                    source: decodeSource(row.source),
+                },
+            };
+
+            if (epoch !== undefined) {
+                this.entries.set(key, cached);
+            }
+        }
+
+        return {
+            ...cached.entry,
+            properties: { ...cached.entry.properties },
+            attributes: { ...cached.entry.attributes },
+            source: { ...cached.entry.source },
+        };
+    }
+
+    clear(): void {
+        this.entries.clear();
+        this.selections.clear();
+    }
+
+    private refresh(epoch: number | undefined): void {
+        if (epoch === undefined || this.epoch !== epoch) {
+            this.clear();
+            this.epoch = epoch;
+        }
+    }
+}

package/src/storage/sqlite/connections.ts

@@ -0,0 +1,49 @@
+import type { Database } from "bun:sqlite";
+
+const connectionsMax = 4;
+const connectionBytesMax = 64 * 1024 * 1024;
+const connections = new Map<Uint8Array, Database>();
+let bytes = 0;
+
+/** Retain clean native connections, never a disposed world's storage wrapper or callbacks. */
+export function takeConnection(image: Uint8Array): Database | undefined {
+    const connection = connections.get(image);
+
+    if (connection) {
+        connections.delete(image);
+        bytes -= image.byteLength;
+    }
+
+    return connection;
+}
+
+export function retainConnection(image: Uint8Array, connection: Database): boolean {
+    if (image.byteLength > connectionBytesMax) {
+        return false;
+    }
+
+    takeConnection(image)?.close();
+
+    while (connections.size >= connectionsMax || bytes + image.byteLength > connectionBytesMax) {
+        const oldest = connections.keys().next().value;
+
+        if (oldest === undefined) {
+            throw new Error("Connection eviction requires an existing idle database.");
+        }
+
+        takeConnection(oldest)?.close();
+    }
+
+    connections.set(image, connection);
+    bytes += image.byteLength;
+
+    return true;
+}
+
+process.once("exit", () => {
+    for (const connection of connections.values()) {
+        connection.close();
+    }
+
+    connections.clear();
+});

package/src/storage/sqlite/errors.ts

@@ -0,0 +1,23 @@
+export type StorageErrorCode =
+    | "STORAGE_CLOSED"
+    | "INVALID_SCHEMA"
+    | "INCOMPATIBLE_SCHEMA"
+    | "UNKNOWN_ITEM_TYPE"
+    | "INVALID_ITEM"
+    | "ITEM_EXISTS"
+    | "ITEM_NOT_FOUND"
+    | "TRANSACTION_STATE"
+    | "INVALID_SNAPSHOT"
+    | "CORRUPT_STORAGE";
+
+export class StorageError extends Error {
+    override readonly name = "StorageError";
+
+    constructor(
+        readonly code: StorageErrorCode,
+        message: string,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}

package/src/storage/sqlite/index.ts

@@ -0,0 +1,13 @@
+export { StorageError } from "./errors.js";
+export type { StorageErrorCode } from "./errors.js";
+export { SqliteStorage } from "./storage.js";
+export type {
+    CatalogEntry,
+    HarnessStorage,
+    ItemTypeDefinition,
+    PackageDocument,
+    PropertyDefinition,
+    StorageValue,
+    StoredItem,
+    TransactionBoundary,
+} from "../types.js";

package/src/storage/sqlite/metadata.ts

@@ -0,0 +1,216 @@
+import { parseFrozenJson } from "../../core/data.js";
+import { dataBytesMax } from "../../core/limits.js";
+import type { SourceLocation } from "../../diagnostics/source-location.js";
+import type { ItemTypeDefinition, PropertyDefinition, StorageValue } from "../types.js";
+import { StorageError } from "./errors.js";
+
+const definitions = new Map<string, ItemTypeDefinition>();
+const definitionCacheEntriesMax = 512;
+const definitionCacheBytesMax = 4 * 1024 * 1024;
+let definitionCacheBytes = 0;
+const presences = new Map<string, readonly string[]>();
+const presenceCacheEntriesMax = 128;
+const presenceTextBytesMax = 16 * 1024;
+
+function record(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function source(value: unknown): value is SourceLocation {
+    return (
+        record(value) &&
+        typeof value.file === "string" &&
+        typeof value.line === "number" &&
+        typeof value.column === "number" &&
+        typeof value.path === "string"
+    );
+}
+
+function property(value: unknown): value is PropertyDefinition {
+    return (
+        record(value) &&
+        typeof value.name === "string" &&
+        typeof value.dataType === "string" &&
+        (value.id === undefined || typeof value.id === "string") &&
+        (value.dataSource === undefined || typeof value.dataSource === "string") &&
+        (value.foreignProperty === undefined || typeof value.foreignProperty === "string") &&
+        (value.isFederated === undefined || typeof value.isFederated === "boolean") &&
+        (value.isRequired === undefined || typeof value.isRequired === "boolean") &&
+        (value.defaultValue === undefined ||
+            value.defaultValue === null ||
+            typeof value.defaultValue === "string" ||
+            (typeof value.defaultValue === "number" && Number.isFinite(value.defaultValue))) &&
+        (value.source === undefined || source(value.source))
+    );
+}
+
+function definition(value: unknown): value is ItemTypeDefinition {
+    return (
+        record(value) &&
+        typeof value.id === "string" &&
+        typeof value.name === "string" &&
+        (value.tableName === undefined || typeof value.tableName === "string") &&
+        (value.isRelationship === undefined || typeof value.isRelationship === "boolean") &&
+        (value.isVersionable === undefined || typeof value.isVersionable === "boolean") &&
+        Array.isArray(value.properties) &&
+        value.properties.every(property) &&
+        (value.source === undefined || source(value.source))
+    );
+}
+
+function parse(text: string): unknown {
+    try {
+        if (text.length > dataBytesMax) {
+            throw new TypeError("Stored metadata exceeds its text limit.");
+        }
+
+        return parseFrozenJson(text);
+    } catch (error) {
+        throw new StorageError("CORRUPT_STORAGE", "Stored metadata is not valid JSON.", {
+            cause: error,
+        });
+    }
+}
+
+export function decodeDefinition(text: string): ItemTypeDefinition {
+    const cached = definitions.get(text);
+
+    if (cached) {
+        definitions.delete(text);
+        definitions.set(text, cached);
+
+        return cached;
+    }
+
+    const value = parse(text);
+
+    if (!definition(value)) {
+        throw new StorageError("CORRUPT_STORAGE", "Stored ItemType metadata has an invalid shape.");
+    }
+
+    const bytes = text.length * 3;
+
+    if (bytes <= definitionCacheBytesMax) {
+        while (
+            definitions.size >= definitionCacheEntriesMax ||
+            definitionCacheBytes + bytes > definitionCacheBytesMax
+        ) {
+            const oldest = definitions.keys().next().value;
+
+            if (oldest === undefined) {
+                throw new Error("Definition cache eviction requires an existing entry.");
+            }
+
+            definitions.delete(oldest);
+            definitionCacheBytes -= oldest.length * 3;
+        }
+
+        definitions.set(text, value);
+        definitionCacheBytes += bytes;
+    }
+
+    return value;
+}
+
+export function decodeProperties(text: string): Record<string, StorageValue> {
+    const value = parse(text);
+
+    if (
+        !record(value) ||
+        !Object.values(value).every(
+            (entry) =>
+                entry === null ||
+                typeof entry === "string" ||
+                (typeof entry === "number" && Number.isFinite(entry)),
+        )
+    ) {
+        throw new StorageError(
+            "CORRUPT_STORAGE",
+            "Stored catalog properties have an invalid shape.",
+        );
+    }
+
+    const result: Record<string, StorageValue> = {};
+
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === null || typeof entry === "string" || typeof entry === "number") {
+            Object.defineProperty(result, key, {
+                value: entry,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+
+    return result;
+}
+
+export function decodeAttributes(text: string): Record<string, string> {
+    const value = parse(text);
+
+    if (!record(value) || !Object.values(value).every((entry) => typeof entry === "string")) {
+        throw new StorageError("CORRUPT_STORAGE", "Stored attributes have an invalid shape.");
+    }
+
+    const result: Record<string, string> = {};
+
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === "string") {
+            Object.defineProperty(result, key, {
+                value: entry,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+
+    return result;
+}
+
+export function decodeSource(text: string): SourceLocation {
+    const value = parse(text);
+
+    if (!source(value)) {
+        throw new StorageError("CORRUPT_STORAGE", "Stored source location has an invalid shape.");
+    }
+
+    return value;
+}
+
+export function decodePresentProperties(text: string): readonly string[] {
+    const cached = presences.get(text);
+
+    if (cached) {
+        presences.delete(text);
+        presences.set(text, cached);
+
+        return cached;
+    }
+
+    const value = parse(text);
+
+    if (
+        !Array.isArray(value) ||
+        !value.every((entry): entry is string => typeof entry === "string")
+    ) {
+        throw new StorageError("CORRUPT_STORAGE", "Stored property presence has an invalid shape.");
+    }
+
+    if (text.length * 3 <= presenceTextBytesMax) {
+        if (presences.size >= presenceCacheEntriesMax) {
+            const oldest = presences.keys().next().value;
+
+            if (oldest === undefined) {
+                throw new Error("Presence cache eviction requires an existing entry.");
+            }
+
+            presences.delete(oldest);
+        }
+
+        presences.set(text, value);
+    }
+
+    return value;
+}