@telepath-computer/autofile 0.0.0-stage → 0.4.0

package/dist/store.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Autofile owns one data folder: record and type operations, blob uploads and
+ * reads, and shared change subscriptions. Operations read current files;
+ * protocol adapters translate these values without owning a second persistence
+ * implementation.
+ */
+import { type JsonObject } from "./json.js";
+import { type PreparedSchema } from "./schema.js";
+export type { JsonObject, JsonPrimitive, JsonValue } from "./json.js";
+/** One reason an operation was refused, with an address when applicable. */
+export interface AutofileProblem {
+    uri?: string;
+    message: string;
+}
+/** A refused operation, with every problem the caller can correct. */
+export declare class AutofileError extends Error {
+    readonly problems: AutofileProblem[];
+    constructor(problems: AutofileProblem[]);
+}
+/** A record with its address, identity, and optional display title. */
+export interface AutofileRecord {
+    uri: string;
+    type: string;
+    key: string;
+    title?: string;
+    problems?: AutofileProblem[];
+    createdAt: string;
+    updatedAt: string;
+    value: JsonObject;
+}
+/** Optional filters and paging controls; where and fields apply only to value. */
+export interface RecordQuery {
+    type?: string | string[];
+    q?: string;
+    where?: JsonObject;
+    fields?: string[];
+    limit?: number;
+    cursor?: string;
+}
+/** One page of matching records and records that could not be returned. */
+export interface RecordQueryResult {
+    records: AutofileRecord[];
+    unreadable: {
+        uri: string;
+        message: string;
+    }[];
+    cursor?: string;
+}
+/** The fields stored in a type declaration. */
+export interface TypeDefinition {
+    description: string;
+    schema: JsonObject;
+    titleField?: string;
+    title?: string;
+}
+/** A type declaration together with its name and address. */
+export interface TypeDeclaration extends TypeDefinition {
+    uri: string;
+    type: string;
+    problems?: AutofileProblem[];
+}
+/** Changes to a declaration; null removes the title or title field. */
+export type TypeChanges = Partial<Omit<TypeDefinition, "titleField" | "title">> & {
+    titleField?: string | null;
+    title?: string | null;
+};
+/** A record or type was created, changed, or deleted. */
+export interface ChangeEvent {
+    uri: string;
+    kind: "created" | "changed" | "deleted";
+}
+type ChangeListener = (changes: ChangeEvent[]) => void | Promise<void>;
+/** Handles failures from this subscription or from change monitoring. */
+export interface WatchOptions {
+    onError?: (error: Error) => void;
+}
+/** The store implementation. Construction resolves paths but performs no I/O. */
+export declare class Autofile {
+    #private;
+    constructor(options: {
+        folder: string;
+    });
+    readonly records: {
+        find: (query?: RecordQuery) => Promise<RecordQueryResult>;
+        get: (uri: string) => Promise<AutofileRecord | undefined>;
+        create: (type: string, value: JsonObject, options?: {
+            key?: string;
+        }) => Promise<AutofileRecord>;
+        update: (uri: string, patch: JsonObject) => Promise<AutofileRecord>;
+        delete: (uri: string) => Promise<void>;
+    };
+    readonly types: {
+        list: () => Promise<TypeDeclaration[]>;
+        get: (name: string) => Promise<TypeDeclaration | undefined>;
+        create: (name: string, definition: TypeDefinition) => Promise<TypeDeclaration>;
+        update: (name: string, changes: TypeChanges) => Promise<TypeDeclaration>;
+        delete: (name: string) => Promise<void>;
+    };
+    readonly blobs: {
+        put: (bytes: Uint8Array, mediaType: string) => Promise<string>;
+        get: (uri: string) => Promise<{
+            bytes: Uint8Array;
+            mimeType: string;
+        } | undefined>;
+    };
+    /** Checks a schema without accessing storage or checking link targets. */
+    static prepareSchema(schema: JsonObject): Promise<PreparedSchema>;
+    /** Subscribes after the shared watcher is ready; the returned function unsubscribes. */
+    watch(onChange: ChangeListener, options?: WatchOptions): Promise<() => Promise<void>>;
+    /** Stops change subscriptions. Future operations on this instance are refused. */
+    close(): Promise<void>;
+}