@telepath-computer/autofile 0.3.0 → 0.4.0

package/dist/store.d.ts

@@ -1,132 +1,112 @@
 /**
- * Reads and writes Autofile's on-disk types and records, and exposes recognized
- * records, declarations, and blobs as plain resource data. Each operation reads
- * current files and keeps protocol-specific behavior outside the store.
+ * 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 JsonObject } from "./json.js";
+import { type PreparedSchema } from "./schema.js";
 export type { JsonObject, JsonPrimitive, JsonValue } from "./json.js";
-export interface StoreError {
+/** One reason an operation was refused, with an address when applicable. */
+export interface AutofileProblem {
     uri?: string;
     message: string;
 }
-export interface Refusal {
-    errors: StoreError[];
+/** A refused operation, with every problem the caller can correct. */
+export declare class AutofileError extends Error {
+    readonly problems: AutofileProblem[];
+    constructor(problems: AutofileProblem[]);
 }
-export interface OpenStoreOptions {
-    dataFolder?: string;
-    writeLockPath?: string;
-}
-/** Transport-sensitive permissions for a record write. */
-export interface RecordWriteOptions {
-    allowLocalPaths?: boolean;
-}
-export interface Store {
-    findRecords(input: FindRecordsInput): Promise<FindRecordsResult | Refusal>;
-    getRecord(input: GetRecordInput): Promise<RecordResult | Refusal>;
-    createRecord(input: CreateRecordInput, options?: RecordWriteOptions): Promise<UriResult | Refusal>;
-    updateRecord(input: UpdateRecordInput, options?: RecordWriteOptions): Promise<UriResult | Refusal>;
-    deleteRecord(input: DeleteRecordInput): Promise<UriResult | Refusal>;
-    listTypes(input: Record<string, never>): Promise<ListTypesResult>;
-    getType(input: GetTypeInput): Promise<TypeResult | Refusal>;
-    createType(input: CreateTypeInput): Promise<UriResult | Refusal>;
-    updateType(input: UpdateTypeInput): Promise<UpdateTypeResult | Refusal>;
-    deleteType(input: DeleteTypeInput): Promise<UriResult | Refusal>;
-    listResources(): Promise<StoreResource[]>;
-    getResourceMetadata(uri: string): Promise<StoreResource | undefined>;
-    listResourceFolder(folder: string): Promise<StoreResource[]>;
-    listTypeResources(type: string): Promise<StoreResource[]>;
-    readResource(uri: string): Promise<StoreResourceContents | undefined>;
-}
-export interface FindRecordsInput {
-    type: string;
-    q?: string;
-    where?: JsonObject;
-    limit?: number;
-    fields?: string[];
-    cursor?: string;
-}
-export interface GetRecordInput {
+/** A record with its address, identity, and optional display title. */
+export interface AutofileRecord {
     uri: string;
-}
-export interface CreateRecordInput {
     type: string;
-    key?: string;
-    record: JsonObject;
-}
-export interface UpdateRecordInput {
-    uri: string;
-    patch: JsonObject;
-}
-export interface DeleteRecordInput {
-    uri: string;
-}
-export interface GetTypeInput {
-    type: string;
-}
-export interface CreateTypeInput {
-    type: string;
-    description: string;
-    schema: JsonObject;
-    titleField?: string;
-}
-export interface UpdateTypeInput {
-    type: string;
-    description?: string;
-    schema?: JsonObject;
-    titleField?: string | null;
-}
-export interface DeleteTypeInput {
-    type: string;
-}
-export interface UriResult {
-    uri: string;
-}
-export interface FindRecordsResult {
-    records: RecordResult[];
-    errors: StoreError[];
-    cursor?: string;
-}
-export interface RecordResult extends UriResult {
+    key: string;
+    title?: string;
+    problems?: AutofileProblem[];
     createdAt: string;
     updatedAt: string;
     value: JsonObject;
-    error?: string;
 }
-export interface TypeSummary extends UriResult {
-    type: string;
-    description: string;
+/** 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;
 }
-export interface ListTypesResult {
-    types: TypeSummary[];
+/** One page of matching records and records that could not be returned. */
+export interface RecordQueryResult {
+    records: AutofileRecord[];
+    unreadable: {
+        uri: string;
+        message: string;
+    }[];
+    cursor?: string;
 }
-export interface TypeResult extends UriResult {
+/** The fields stored in a type declaration. */
+export interface TypeDefinition {
     description: string;
     schema: JsonObject;
     titleField?: string;
-}
-export interface UpdateTypeResult extends UriResult {
-    errors: StoreError[];
-}
-/** Plain metadata for one resource recognized in the data folder. */
-export interface StoreResource extends UriResult {
-    name: string;
-    mimeType: string;
     title?: string;
-    description?: string;
-    size?: number;
-    lastModified?: string;
 }
-/** Exact contents of a recognized text or binary resource. */
-export type StoreResourceContents = {
+/** A type declaration together with its name and address. */
+export interface TypeDeclaration extends TypeDefinition {
     uri: string;
-    mimeType: string;
-    text: string;
-} | {
-    uri: string;
-    mimeType: string;
-    blob: 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;
 };
-/** Opens a store, creating its data folder when it does not exist. */
-export declare function openStore(options?: OpenStoreOptions): Promise<Store>;
-/** Returns whether a string is the canonical URI of an Autofile resource. */
-export declare function isResourceUri(uri: string): boolean;
+/** 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>;
+}