@powerhousedao/reactor-api 1.3.4 → 1.4.1

package/CHANGELOG.md

@@ -1,20 +1,9 @@
-## 1.3.4 (2024-11-11)
-
-### 🚀 Features
-
-- **codegen:** regenerate lockfile ([31c2d0c5](https://github.com/powerhouse-inc/powerhouse/commit/31c2d0c5))
-- **ph-cli:** update cli to format by default ([7418e777](https://github.com/powerhouse-inc/powerhouse/commit/7418e777))
-- **codegen:** remove format generated from action ([5d7e1c48](https://github.com/powerhouse-inc/powerhouse/commit/5d7e1c48))
-- **codegen:** use prettier api to format typescript from gql ([8896d86e](https://github.com/powerhouse-inc/powerhouse/commit/8896d86e))
+## 1.4.1 (2024-11-11)
 
 ### 🧱 Updated Dependencies
 
-- Updated document-model-libs to 1.110.0
-- Updated document-drive to 1.3.4
-
-### ❤️  Thank You
-
-- ryanwolhuter @ryanwolhuter
+- Updated document-model-libs to 1.111.0
+- Updated document-drive to 1.4.1
 
 ## 1.2.0 (2024-10-29)
 

package/dist/index.d.ts

@@ -1,14 +1,289 @@
-import * as document_drive from 'document-drive';
-import { BaseDocumentDriveServer, Listener, InternalTransmitterUpdate } from 'document-drive';
+import { Trigger, PullResponderTriggerData, DocumentDriveDocument, ListenerFilter, DocumentDriveLocalState, ListenerCallInfo, DocumentDriveAction, DocumentDriveState } from 'document-model-libs/document-drive';
+import { Document, OperationScope, Operation, DocumentModel, Action, ActionContext, BaseAction, State, CreateChildDocumentInput, ReducerOptions, Signal } from 'document-model/document';
+import { Unsubscribe } from 'nanoevents';
 import express, { Express, IRouter } from 'express';
 import * as graphql from 'graphql';
 import { GraphQLResolverMap } from '@apollo/subgraph/dist/schema-helper';
 
+type StrandUpdateSource = {
+    type: "local";
+} | {
+    type: "trigger";
+    trigger: Trigger;
+};
+interface ITransmitter {
+    transmit?(strands: StrandUpdate[], source: StrandUpdateSource): Promise<ListenerRevision[]>;
+    disconnect?(): Promise<void>;
+}
+type PullResponderTrigger = Omit<Trigger, "data" | "type"> & {
+    data: PullResponderTriggerData;
+    type: "PullResponder";
+};
+
+interface IReceiver {
+    transmit: (strands: InternalTransmitterUpdate[]) => Promise<void>;
+    disconnect: () => Promise<void>;
+}
+type InternalTransmitterUpdate<T extends Document = Document, S extends OperationScope = OperationScope> = {
+    driveId: string;
+    documentId: string;
+    scope: S;
+    branch: string;
+    operations: OperationUpdate[];
+    state: T["state"][S];
+};
+interface IInternalTransmitter extends ITransmitter {
+    setReceiver(receiver: IReceiver): void;
+}
+
+declare class DocumentModelNotFoundError extends Error {
+    id: string;
+    constructor(id: string, cause?: unknown);
+}
+declare class OperationError extends Error {
+    status: ErrorStatus;
+    operation: Operation | undefined;
+    constructor(status: ErrorStatus, operation?: Operation, message?: string, cause?: unknown);
+}
+declare class SynchronizationUnitNotFoundError extends Error {
+    syncUnitId: string;
+    constructor(message: string, syncUnitId: string);
+}
+
+type DriveInfo = {
+    id: string;
+    name: string;
+    slug: string;
+    icon?: string;
+};
+
+declare abstract class ReadDriveError extends Error {
+}
+declare class ReadDriveNotFoundError extends ReadDriveError {
+    constructor(driveId: string);
+}
+declare class ReadDriveSlugNotFoundError extends ReadDriveError {
+    constructor(slug: string);
+}
+declare class ReadDocumentNotFoundError extends ReadDriveError {
+    constructor(drive: string, id: string);
+}
+
+type InferDocumentState<D extends Document> = D extends Document<infer S> ? S : never;
+type InferDocumentOperation<D extends Document> = D extends Document<unknown, infer A> ? A : never;
+type InferDocumentLocalState<D extends Document> = D extends Document<unknown, Action, infer L> ? L : never;
+type ReadDrivesListener = (drives: ReadDrive[], operation: "add" | "delete") => void;
+type ReadDrivesListenerUnsubscribe = () => void;
+interface IReadModeDriveServer extends IReadModeDriveService {
+    migrateReadDrive(id: string, options: RemoteDriveOptions): Promise<DocumentDriveDocument | ReadDriveNotFoundError>;
+    onReadDrivesUpdate(listener: ReadDrivesListener): Promise<ReadDrivesListenerUnsubscribe>;
+}
+type ReadDriveOptions = {
+    expectedDriveInfo?: DriveInfo;
+    filter?: ListenerFilter;
+};
+type ReadDriveContext = {
+    url: string;
+} & ReadDriveOptions;
+type ReadDrive = DocumentDriveDocument & {
+    readContext: ReadDriveContext;
+};
+interface IReadModeDriveService {
+    addReadDrive(url: string, options?: ReadDriveOptions): Promise<void>;
+    getReadDrives(): Promise<string[]>;
+    getReadDriveBySlug(slug: string): Promise<ReadDrive | ReadDriveSlugNotFoundError>;
+    getReadDrive(id: string): Promise<ReadDrive | ReadDriveNotFoundError>;
+    getReadDriveContext(id: string): Promise<ReadDriveContext | ReadDriveNotFoundError>;
+    fetchDrive(id: string): Promise<ReadDrive | ReadDriveNotFoundError>;
+    fetchDocument<D extends Document>(driveId: string, documentId: string, documentType: DocumentModel<InferDocumentState<D>, InferDocumentOperation<D>, InferDocumentLocalState<D>>["documentModel"]["id"]): Promise<Document<InferDocumentState<D>, InferDocumentOperation<D>, InferDocumentLocalState<D>> | DocumentModelNotFoundError | ReadDriveNotFoundError | ReadDocumentNotFoundError>;
+    deleteReadDrive(id: string): Promise<ReadDriveNotFoundError | undefined>;
+}
+
+interface IDefaultDrivesManager {
+    initializeDefaultRemoteDrives(): Promise<void>;
+    getDefaultRemoteDrives(): Map<string, DefaultRemoteDriveInfo>;
+    setDefaultDriveAccessLevel(url: string, level: RemoteDriveAccessLevel): Promise<void>;
+    setAllDefaultDrivesAccessLevel(level: RemoteDriveAccessLevel): Promise<void>;
+}
+
+type DriveInput = State<Omit<DocumentDriveState, "__typename" | "id" | "nodes"> & {
+    id?: string;
+}, DocumentDriveLocalState>;
+type RemoteDriveAccessLevel = "READ" | "WRITE";
+type RemoteDriveOptions = DocumentDriveLocalState & {
+    pullFilter?: ListenerFilter;
+    pullInterval?: number;
+    expectedDriveInfo?: DriveInfo;
+    accessLevel?: RemoteDriveAccessLevel;
+};
+type CreateDocumentInput = CreateChildDocumentInput;
+type SignalResult = {
+    signal: Signal;
+    result: unknown;
+};
+type IOperationResult<T extends Document = Document> = {
+    status: UpdateStatus;
+    error?: OperationError;
+    operations: Operation[];
+    document: T | undefined;
+    signals: SignalResult[];
+};
+type SynchronizationUnit = {
+    syncId: string;
+    driveId: string;
+    documentId: string;
+    documentType: string;
+    scope: string;
+    branch: string;
+    lastUpdated: string;
+    revision: number;
+};
+type SynchronizationUnitQuery = Omit<SynchronizationUnit, "revision" | "lastUpdated">;
+type Listener = {
+    driveId: string;
+    listenerId: string;
+    label?: string;
+    block: boolean;
+    system: boolean;
+    filter: ListenerFilter;
+    callInfo?: ListenerCallInfo;
+};
+type ListenerRevision = {
+    driveId: string;
+    documentId: string;
+    scope: string;
+    branch: string;
+    status: UpdateStatus;
+    revision: number;
+    error?: string;
+};
+type UpdateStatus = "SUCCESS" | "CONFLICT" | "MISSING" | "ERROR";
+type ErrorStatus = Exclude<UpdateStatus, "SUCCESS">;
+type OperationUpdate = {
+    timestamp: string;
+    index: number;
+    skip: number;
+    type: string;
+    input: object;
+    hash: string;
+    context?: ActionContext;
+    id?: string;
+};
+type StrandUpdate = {
+    driveId: string;
+    documentId: string;
+    scope: OperationScope;
+    branch: string;
+    operations: OperationUpdate[];
+};
+type SyncStatus = "INITIAL_SYNC" | "SYNCING" | UpdateStatus;
+type PullSyncStatus = SyncStatus;
+type PushSyncStatus = SyncStatus;
+type SyncUnitStatusObject = {
+    push?: PushSyncStatus;
+    pull?: PullSyncStatus;
+};
+type AddRemoteDriveStatus = "SUCCESS" | "ERROR" | "PENDING" | "ADDING" | "ALREADY_ADDED";
+interface DriveEvents {
+    syncStatus: (driveId: string, status: SyncStatus, error?: Error, syncUnitStatus?: SyncUnitStatusObject) => void;
+    defaultRemoteDrive: (status: AddRemoteDriveStatus, defaultDrives: Map<string, DefaultRemoteDriveInfo>, driveInput: DefaultRemoteDriveInput, driveId?: string, driveName?: string, error?: Error) => void;
+    strandUpdate: (update: StrandUpdate) => void;
+    clientStrandsError: (driveId: string, trigger: Trigger, status: number, errorMessage: string) => void;
+    documentModels: (documentModels: DocumentModel[]) => void;
+    driveAdded: (drive: DocumentDriveDocument) => void;
+    driveDeleted: (driveId: string) => void;
+}
+type PartialRecord<K extends keyof any, T> = {
+    [P in K]?: T;
+};
+type RevisionsFilter = PartialRecord<OperationScope, number>;
+type GetDocumentOptions = ReducerOptions & {
+    revisions?: RevisionsFilter;
+    checkHashes?: boolean;
+};
+type AddOperationOptions = {
+    forceSync?: boolean;
+    source: StrandUpdateSource;
+};
+type DefaultRemoteDriveInput = {
+    url: string;
+    options: RemoteDriveOptions;
+};
+type DefaultRemoteDriveInfo = DefaultRemoteDriveInput & {
+    status: AddRemoteDriveStatus;
+    metadata?: DriveInfo;
+};
+type GetStrandsOptions = {
+    limit?: number;
+    since?: string;
+    fromRevision?: number;
+};
+declare abstract class AbstractDocumentDriveServer {
+    /** Public methods **/
+    abstract initialize(): Promise<Error[] | null>;
+    abstract setDocumentModels(models: DocumentModel[]): void;
+    abstract getDrives(): Promise<string[]>;
+    abstract addDrive(drive: DriveInput): Promise<DocumentDriveDocument>;
+    abstract addRemoteDrive(url: string, options: RemoteDriveOptions): Promise<DocumentDriveDocument>;
+    abstract deleteDrive(id: string): Promise<void>;
+    abstract getDrive(id: string, options?: GetDocumentOptions): Promise<DocumentDriveDocument>;
+    abstract getDriveBySlug(slug: string): Promise<DocumentDriveDocument>;
+    abstract getDocuments(drive: string): Promise<string[]>;
+    abstract getDocument(drive: string, id: string, options?: GetDocumentOptions): Promise<Document>;
+    abstract addOperation(drive: string, id: string, operation: Operation, options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract addOperations(drive: string, id: string, operations: Operation[], options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract queueOperation(drive: string, id: string, operation: Operation, options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract queueOperations(drive: string, id: string, operations: Operation[], options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract queueAction(drive: string, id: string, action: Action, options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract queueActions(drive: string, id: string, actions: Action[], options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract addDriveOperation(drive: string, operation: Operation<DocumentDriveAction | BaseAction>, options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract addDriveOperations(drive: string, operations: Operation<DocumentDriveAction | BaseAction>[], options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract queueDriveOperation(drive: string, operation: Operation<DocumentDriveAction | BaseAction>, options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract queueDriveOperations(drive: string, operations: Operation<DocumentDriveAction | BaseAction>[], options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract queueDriveAction(drive: string, action: DocumentDriveAction | BaseAction, options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract queueDriveActions(drive: string, actions: Array<DocumentDriveAction | BaseAction>, options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract addAction(drive: string, id: string, action: Action, options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract addActions(drive: string, id: string, actions: Action[], options?: AddOperationOptions): Promise<IOperationResult>;
+    abstract addDriveAction(drive: string, action: DocumentDriveAction | BaseAction, options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract addDriveActions(drive: string, actions: (DocumentDriveAction | BaseAction)[], options?: AddOperationOptions): Promise<IOperationResult<DocumentDriveDocument>>;
+    abstract getSyncStatus(syncUnitId: string): SyncStatus | SynchronizationUnitNotFoundError;
+    abstract addInternalListener(driveId: string, receiver: IReceiver, options: {
+        listenerId: string;
+        label: string;
+        block: boolean;
+        filter: ListenerFilter;
+    }): Promise<IInternalTransmitter>;
+    /** Synchronization methods */
+    abstract getSynchronizationUnits(driveId: string, documentId?: string[], scope?: string[], branch?: string[], documentType?: string[], loadedDrive?: DocumentDriveDocument): Promise<SynchronizationUnit[]>;
+    abstract getSynchronizationUnit(driveId: string, syncId: string, loadedDrive?: DocumentDriveDocument): Promise<SynchronizationUnit | undefined>;
+    abstract getSynchronizationUnitsIds(driveId: string, documentId?: string[], scope?: string[], branch?: string[], documentType?: string[]): Promise<SynchronizationUnitQuery[]>;
+    abstract getOperationData(driveId: string, syncId: string, filter: GetStrandsOptions, loadedDrive?: DocumentDriveDocument): Promise<OperationUpdate[]>;
+    /** Internal methods **/
+    protected abstract createDocument(drive: string, document: CreateDocumentInput): Promise<Document>;
+    protected abstract deleteDocument(drive: string, id: string): Promise<void>;
+    protected abstract getDocumentModel(documentType: string): DocumentModel;
+    abstract getDocumentModels(): DocumentModel[];
+    /** Event methods **/
+    protected abstract emit<K extends keyof DriveEvents>(event: K, ...args: Parameters<DriveEvents[K]>): void;
+    abstract on<K extends keyof DriveEvents>(event: K, cb: DriveEvents[K]): Unsubscribe;
+    abstract getTransmitter(driveId: string, listenerId: string): Promise<ITransmitter | undefined>;
+    abstract clearStorage(): Promise<void>;
+    abstract registerPullResponderTrigger(id: string, url: string, options: Pick<RemoteDriveOptions, "pullFilter" | "pullInterval">): Promise<PullResponderTrigger>;
+}
+type PublicKeys<T> = {
+    [K in keyof T]: T extends {
+        [P in K]: T[K];
+    } ? K : never;
+}[keyof T];
+type PublicPart<T> = Pick<T, PublicKeys<T>>;
+type IBaseDocumentDriveServer = PublicPart<AbstractDocumentDriveServer>;
+type IDocumentDriveServer = IBaseDocumentDriveServer & IDefaultDrivesManager & IReadModeDriveServer;
+
 type Options = {
     express?: Express;
     port?: number;
 };
-declare function startAPI(reactor: BaseDocumentDriveServer, options: Options): Promise<void>;
+declare function startAPI(reactor: IDocumentDriveServer, options: Options): Promise<void>;
 
 type InternalListenerModule = {
     name: string;
@@ -19,26 +294,26 @@ declare class InternalListenerManager {
     #private;
     private driveServer;
     private modules;
-    constructor(driveServer: BaseDocumentDriveServer);
+    constructor(driveServer: IDocumentDriveServer);
     init(): Promise<void>;
     registerInternalListener(module: InternalListenerModule): Promise<void>;
 }
 
 declare const SUBGRAPH_REGISTRY: {
     name: string;
-    getSchema: (driveServer: document_drive.BaseDocumentDriveServer) => graphql.GraphQLSchema;
+    getSchema: (driveServer: IDocumentDriveServer) => graphql.GraphQLSchema;
 }[];
 
 declare let reactorRouter: IRouter;
-declare const getListenerManager: (driveServer: BaseDocumentDriveServer) => Promise<InternalListenerManager>;
-declare const updateRouter: (driveServer: BaseDocumentDriveServer) => Promise<void>;
-declare const initReactorRouter: (path: string, app: express.Express, driveServer: BaseDocumentDriveServer) => Promise<void>;
+declare const getListenerManager: (driveServer: IDocumentDriveServer) => Promise<InternalListenerManager>;
+declare const updateRouter: (driveServer: IDocumentDriveServer) => Promise<void>;
+declare const initReactorRouter: (path: string, app: express.Express, driveServer: IDocumentDriveServer) => Promise<void>;
 declare const addSubgraph: (subgraph: (typeof SUBGRAPH_REGISTRY)[number]) => Promise<void>;
 declare const registerInternalListener: (module: InternalListenerModule) => Promise<void>;
 declare const getAdditionalContextFields: () => {};
 declare const setAdditionalContextFields: (fields: Record<string, any>) => void;
 
-declare const createSchema: (documentDriveServer: BaseDocumentDriveServer, resolvers: GraphQLResolverMap, typeDefs: string) => graphql.GraphQLSchema;
-declare const getDocumentModelTypeDefs: (documentDriveServer: BaseDocumentDriveServer, typeDefs: string) => graphql.DocumentNode;
+declare const createSchema: (documentDriveServer: IDocumentDriveServer, resolvers: GraphQLResolverMap, typeDefs: string) => graphql.GraphQLSchema;
+declare const getDocumentModelTypeDefs: (documentDriveServer: IDocumentDriveServer, typeDefs: string) => graphql.DocumentNode;
 
 export { addSubgraph, createSchema, getAdditionalContextFields, getDocumentModelTypeDefs, getListenerManager, initReactorRouter, reactorRouter, registerInternalListener, setAdditionalContextFields, startAPI, updateRouter };