@dossierhq/core/lib/client/DossierClient.d.ts

The core Dossier library used by clients and server alike, used to interact with schema and entities directly, as well as remotely through a client.

import { ErrorType, type ErrorFromResult, type OkFromResult, type PromiseResult, type Result } from '../ErrorResult.js';
import type { ChangelogEvent, ChangelogEventQuery, ChangelogEventSharedQuery } from '../events/EventTypes.js';
import type { SchemaSpecification, SchemaSpecificationUpdate, SchemaSpecificationUpdatePayload, SchemaSpecificationWithMigrations } from '../schema/SchemaSpecification.js';
import type { AdvisoryLockOptions, AdvisoryLockPayload, AdvisoryLockReleasePayload, Component, Connection, Edge, Entity, EntityArchivePayload, EntityCreate, EntityCreatePayload, EntityDeletePayload, EntityMutationOptions, EntityProcessDirtyPayload, EntityPublishPayload, EntityQuery, EntityReference, EntitySamplingOptions, EntitySamplingPayload, EntitySharedQuery, EntityUnarchivePayload, EntityUnpublishPayload, EntityUpdate, EntityUpdatePayload, EntityUpsert, EntityUpsertPayload, EntityVersionReference, Paging, UniqueIndexReference } from '../Types.js';
import type { LooseAutocomplete } from '../utils/TypeUtils.js';
import { type ClientContext, type ContextProvider, type Middleware, type Operation } from './SharedClient.js';
export interface DossierClient<TEntity extends Entity<string, object> = Entity, TComponent extends Component<string, object> = Component, TUniqueIndex extends string = string, TExceptionClient extends DossierExceptionClient<TEntity, TComponent, TUniqueIndex> = DossierExceptionClient<TEntity, TComponent, TUniqueIndex>> {
    getSchemaSpecification(options: {
        includeMigrations: true;
    }): PromiseResult<SchemaSpecificationWithMigrations, typeof ErrorType.Generic>;
    getSchemaSpecification(options?: {
        includeMigrations: boolean;
    }): PromiseResult<SchemaSpecification, typeof ErrorType.Generic>;
    updateSchemaSpecification(schemaSpec: SchemaSpecificationUpdate, options: {
        includeMigrations: true;
    }): PromiseResult<SchemaSpecificationUpdatePayload<SchemaSpecificationWithMigrations>, typeof ErrorType.BadRequest | typeof ErrorType.Generic>;
    updateSchemaSpecification(schemaSpec: SchemaSpecificationUpdate, options?: {
        includeMigrations: boolean;
    }): PromiseResult<SchemaSpecificationUpdatePayload, typeof ErrorType.BadRequest | typeof ErrorType.Generic>;
    getEntity(reference: EntityReference | EntityVersionReference | UniqueIndexReference<TUniqueIndex>): PromiseResult<TEntity, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    getEntityList(references: EntityReference[]): PromiseResult<Result<TEntity, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>[], typeof ErrorType.Generic>;
    getEntities(query?: EntityQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>, paging?: Paging): PromiseResult<Connection<Edge<TEntity, ErrorType>> | null, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    getEntitiesTotalCount(query?: EntitySharedQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>): PromiseResult<number, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    getEntitiesSample(query?: EntitySharedQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>, options?: EntitySamplingOptions): PromiseResult<EntitySamplingPayload<TEntity>, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    createEntity<T extends Entity<string, object> = TEntity>(entity: Readonly<EntityCreate<T>>, options?: EntityMutationOptions): PromiseResult<EntityCreatePayload<T>, typeof ErrorType.BadRequest | typeof ErrorType.Conflict | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    updateEntity<T extends Entity<string, object> = TEntity>(entity: Readonly<EntityUpdate<T>>, options?: EntityMutationOptions): PromiseResult<EntityUpdatePayload<T>, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    upsertEntity<T extends Entity<string, object> = TEntity>(entity: Readonly<EntityUpsert<T>>, options?: EntityMutationOptions): PromiseResult<EntityUpsertPayload<T>, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    getChangelogEvents(query?: ChangelogEventQuery, paging?: Paging): PromiseResult<Connection<Edge<ChangelogEvent, typeof ErrorType.Generic>> | null, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    getChangelogEventsTotalCount(query?: ChangelogEventSharedQuery): PromiseResult<number, typeof ErrorType.BadRequest | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    publishEntities(references: EntityVersionReference[]): PromiseResult<EntityPublishPayload[], typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    unpublishEntities(references: EntityReference[]): PromiseResult<EntityUnpublishPayload[], typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    archiveEntity(reference: EntityReference): PromiseResult<EntityArchivePayload, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    unarchiveEntity(reference: EntityReference): PromiseResult<EntityUnarchivePayload, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    deleteEntities(references: EntityReference[]): PromiseResult<EntityDeletePayload, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>;
    processDirtyEntity(reference: EntityReference): PromiseResult<EntityProcessDirtyPayload | null, typeof ErrorType.BadRequest | typeof ErrorType.Generic>;
    acquireAdvisoryLock(name: string, options: AdvisoryLockOptions): PromiseResult<AdvisoryLockPayload, typeof ErrorType.BadRequest | typeof ErrorType.Conflict | typeof ErrorType.Generic>;
    renewAdvisoryLock(name: string, handle: number): PromiseResult<AdvisoryLockPayload, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.Generic>;
    releaseAdvisoryLock(name: string, handle: number): PromiseResult<AdvisoryLockReleasePayload, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.Generic>;
    toExceptionClient(): TExceptionClient;
}
export interface DossierExceptionClient<TEntity extends Entity<string, object> = Entity, TComponent extends Component<string, object> = Component, TUniqueIndex extends string = string> {
    client: Readonly<DossierClient<TEntity, TComponent, TUniqueIndex>>;
    getSchemaSpecification(options: {
        includeMigrations: true;
    }): Promise<SchemaSpecificationWithMigrations>;
    getSchemaSpecification(options?: {
        includeMigrations: boolean;
    }): Promise<SchemaSpecification>;
    updateSchemaSpecification(schemaSpec: SchemaSpecificationUpdate, options: {
        includeMigrations: true;
    }): Promise<SchemaSpecificationUpdatePayload<SchemaSpecificationWithMigrations>>;
    updateSchemaSpecification(schemaSpec: SchemaSpecificationUpdate, options?: {
        includeMigrations: boolean;
    }): Promise<SchemaSpecificationUpdatePayload>;
    getEntity(reference: EntityReference | EntityVersionReference | UniqueIndexReference<TUniqueIndex>): Promise<TEntity>;
    getEntityList(references: EntityReference[]): Promise<Result<TEntity, typeof ErrorType.BadRequest | typeof ErrorType.NotFound | typeof ErrorType.NotAuthorized | typeof ErrorType.Generic>[]>;
    getEntities(query?: EntityQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>, paging?: Paging): Promise<Connection<Edge<TEntity, ErrorType>> | null>;
    getEntitiesTotalCount(query?: EntitySharedQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>): Promise<number>;
    getEntitiesSample(query?: EntitySharedQuery<TEntity['info']['type'], TComponent['type'], TEntity['info']['authKey']>, options?: EntitySamplingOptions): Promise<EntitySamplingPayload<TEntity>>;
    createEntity<T extends Entity<string, object> = TEntity>(entity: EntityCreate<T>, options?: EntityMutationOptions): Promise<EntityCreatePayload<T>>;
    updateEntity<T extends Entity<string, object> = TEntity>(entity: EntityUpdate<T>, options?: EntityMutationOptions): Promise<EntityUpdatePayload<T>>;
    upsertEntity<T extends Entity<string, object> = TEntity>(entity: EntityUpsert<T>, options?: EntityMutationOptions): Promise<EntityUpsertPayload<T>>;
    getChangelogEvents(query?: ChangelogEventQuery, paging?: Paging): Promise<Connection<Edge<ChangelogEvent, typeof ErrorType.Generic>> | null>;
    getChangelogEventsTotalCount(query?: ChangelogEventQuery): Promise<number>;
    publishEntities(references: EntityVersionReference[]): Promise<EntityPublishPayload[]>;
    unpublishEntities(references: EntityReference[]): Promise<EntityUnpublishPayload[]>;
    archiveEntity(reference: EntityReference): Promise<EntityArchivePayload>;
    unarchiveEntity(reference: EntityReference): Promise<EntityUnarchivePayload>;
    deleteEntities(references: EntityReference[]): Promise<EntityDeletePayload>;
    processDirtyEntity(reference: EntityReference): Promise<EntityProcessDirtyPayload | null>;
    acquireAdvisoryLock(name: string, options: AdvisoryLockOptions): Promise<AdvisoryLockPayload>;
    renewAdvisoryLock(name: string, handle: number): Promise<AdvisoryLockPayload>;
    releaseAdvisoryLock(name: string, handle: number): Promise<AdvisoryLockReleasePayload>;
}
export declare const DossierClientOperationName: {
    readonly acquireAdvisoryLock: "acquireAdvisoryLock";
    readonly archiveEntity: "archiveEntity";
    readonly createEntity: "createEntity";
    readonly deleteEntities: "deleteEntities";
    readonly getChangelogEvents: "getChangelogEvents";
    readonly getChangelogEventsTotalCount: "getChangelogEventsTotalCount";
    readonly getEntities: "getEntities";
    readonly getEntitiesSample: "getEntitiesSample";
    readonly getEntitiesTotalCount: "getEntitiesTotalCount";
    readonly getEntity: "getEntity";
    readonly getEntityList: "getEntityList";
    readonly getSchemaSpecification: "getSchemaSpecification";
    readonly processDirtyEntity: "processDirtyEntity";
    readonly publishEntities: "publishEntities";
    readonly releaseAdvisoryLock: "releaseAdvisoryLock";
    readonly renewAdvisoryLock: "renewAdvisoryLock";
    readonly unarchiveEntity: "unarchiveEntity";
    readonly unpublishEntities: "unpublishEntities";
    readonly updateEntity: "updateEntity";
    readonly updateSchemaSpecification: "updateSchemaSpecification";
    readonly upsertEntity: "upsertEntity";
};
type DossierClientOperationName = keyof typeof DossierClientOperationName;
type MethodParameters<TName extends keyof DossierClient, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient> = Parameters<TClient[TName]>;
type MethodReturnTypeWithoutPromise<TName extends keyof DossierClient, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient> = Awaited<PromiseResult<MethodReturnTypeOk<TName, TClient>, MethodReturnTypeError<TName, TClient>>>;
type MethodReturnTypeOk<TName extends keyof DossierClient, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient> = OkFromResult<ReturnType<TClient[TName]>>;
type MethodReturnTypeError<TName extends keyof DossierClient, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient> = ErrorFromResult<ReturnType<TClient[TName]>>;
interface DossierClientOperationArguments {
    [DossierClientOperationName.acquireAdvisoryLock]: MethodParameters<'acquireAdvisoryLock'>;
    [DossierClientOperationName.archiveEntity]: MethodParameters<'archiveEntity'>;
    [DossierClientOperationName.createEntity]: MethodParameters<'createEntity'>;
    [DossierClientOperationName.deleteEntities]: MethodParameters<'deleteEntities'>;
    [DossierClientOperationName.getChangelogEvents]: MethodParameters<'getChangelogEvents'>;
    [DossierClientOperationName.getChangelogEventsTotalCount]: MethodParameters<'getChangelogEventsTotalCount'>;
    [DossierClientOperationName.getEntities]: MethodParameters<'getEntities'>;
    [DossierClientOperationName.getEntitiesSample]: MethodParameters<'getEntitiesSample'>;
    [DossierClientOperationName.getEntitiesTotalCount]: MethodParameters<'getEntitiesTotalCount'>;
    [DossierClientOperationName.getEntity]: MethodParameters<'getEntity'>;
    [DossierClientOperationName.getEntityList]: MethodParameters<'getEntityList'>;
    [DossierClientOperationName.getSchemaSpecification]: MethodParameters<'getSchemaSpecification'>;
    [DossierClientOperationName.processDirtyEntity]: MethodParameters<'processDirtyEntity'>;
    [DossierClientOperationName.publishEntities]: MethodParameters<'publishEntities'>;
    [DossierClientOperationName.releaseAdvisoryLock]: MethodParameters<'releaseAdvisoryLock'>;
    [DossierClientOperationName.renewAdvisoryLock]: MethodParameters<'renewAdvisoryLock'>;
    [DossierClientOperationName.unarchiveEntity]: MethodParameters<'unarchiveEntity'>;
    [DossierClientOperationName.unpublishEntities]: MethodParameters<'unpublishEntities'>;
    [DossierClientOperationName.updateEntity]: MethodParameters<'updateEntity'>;
    [DossierClientOperationName.updateSchemaSpecification]: MethodParameters<'updateSchemaSpecification'>;
    [DossierClientOperationName.upsertEntity]: MethodParameters<'upsertEntity'>;
}
interface DossierClientOperationReturnOk {
    [DossierClientOperationName.acquireAdvisoryLock]: MethodReturnTypeOk<'acquireAdvisoryLock'>;
    [DossierClientOperationName.archiveEntity]: MethodReturnTypeOk<'archiveEntity'>;
    [DossierClientOperationName.createEntity]: MethodReturnTypeOk<'createEntity'>;
    [DossierClientOperationName.deleteEntities]: MethodReturnTypeOk<'deleteEntities'>;
    [DossierClientOperationName.getChangelogEvents]: MethodReturnTypeOk<'getChangelogEvents'>;
    [DossierClientOperationName.getChangelogEventsTotalCount]: MethodReturnTypeOk<'getChangelogEventsTotalCount'>;
    [DossierClientOperationName.getEntities]: MethodReturnTypeOk<'getEntities'>;
    [DossierClientOperationName.getEntitiesSample]: MethodReturnTypeOk<'getEntitiesSample'>;
    [DossierClientOperationName.getEntitiesTotalCount]: MethodReturnTypeOk<'getEntitiesTotalCount'>;
    [DossierClientOperationName.getEntity]: MethodReturnTypeOk<'getEntity'>;
    [DossierClientOperationName.getEntityList]: MethodReturnTypeOk<'getEntityList'>;
    [DossierClientOperationName.getSchemaSpecification]: MethodReturnTypeOk<'getSchemaSpecification'>;
    [DossierClientOperationName.processDirtyEntity]: MethodReturnTypeOk<'processDirtyEntity'>;
    [DossierClientOperationName.publishEntities]: MethodReturnTypeOk<'publishEntities'>;
    [DossierClientOperationName.releaseAdvisoryLock]: MethodReturnTypeOk<'releaseAdvisoryLock'>;
    [DossierClientOperationName.renewAdvisoryLock]: MethodReturnTypeOk<'renewAdvisoryLock'>;
    [DossierClientOperationName.unarchiveEntity]: MethodReturnTypeOk<'unarchiveEntity'>;
    [DossierClientOperationName.unpublishEntities]: MethodReturnTypeOk<'unpublishEntities'>;
    [DossierClientOperationName.updateEntity]: MethodReturnTypeOk<'updateEntity'>;
    [DossierClientOperationName.updateSchemaSpecification]: MethodReturnTypeOk<'updateSchemaSpecification'>;
    [DossierClientOperationName.upsertEntity]: MethodReturnTypeOk<'upsertEntity'>;
}
interface DossierClientOperationReturnError {
    [DossierClientOperationName.acquireAdvisoryLock]: MethodReturnTypeError<'acquireAdvisoryLock'>;
    [DossierClientOperationName.archiveEntity]: MethodReturnTypeError<'archiveEntity'>;
    [DossierClientOperationName.createEntity]: MethodReturnTypeError<'createEntity'>;
    [DossierClientOperationName.deleteEntities]: MethodReturnTypeError<'deleteEntities'>;
    [DossierClientOperationName.getChangelogEvents]: MethodReturnTypeError<'getChangelogEvents'>;
    [DossierClientOperationName.getChangelogEventsTotalCount]: MethodReturnTypeError<'getChangelogEventsTotalCount'>;
    [DossierClientOperationName.getEntities]: MethodReturnTypeError<'getEntities'>;
    [DossierClientOperationName.getEntitiesSample]: MethodReturnTypeError<'getEntitiesSample'>;
    [DossierClientOperationName.getEntitiesTotalCount]: MethodReturnTypeError<'getEntitiesTotalCount'>;
    [DossierClientOperationName.getEntity]: MethodReturnTypeError<'getEntity'>;
    [DossierClientOperationName.getEntityList]: MethodReturnTypeError<'getEntityList'>;
    [DossierClientOperationName.getSchemaSpecification]: MethodReturnTypeError<'getSchemaSpecification'>;
    [DossierClientOperationName.processDirtyEntity]: MethodReturnTypeError<'processDirtyEntity'>;
    [DossierClientOperationName.publishEntities]: MethodReturnTypeError<'publishEntities'>;
    [DossierClientOperationName.releaseAdvisoryLock]: MethodReturnTypeError<'releaseAdvisoryLock'>;
    [DossierClientOperationName.renewAdvisoryLock]: MethodReturnTypeError<'renewAdvisoryLock'>;
    [DossierClientOperationName.unarchiveEntity]: MethodReturnTypeError<'unarchiveEntity'>;
    [DossierClientOperationName.unpublishEntities]: MethodReturnTypeError<'unpublishEntities'>;
    [DossierClientOperationName.updateEntity]: MethodReturnTypeError<'updateEntity'>;
    [DossierClientOperationName.updateSchemaSpecification]: MethodReturnTypeError<'updateSchemaSpecification'>;
    [DossierClientOperationName.upsertEntity]: MethodReturnTypeError<'upsertEntity'>;
}
export type DossierClientOperation<TName extends DossierClientOperationName = DossierClientOperationName> = Operation<TName, DossierClientOperationArguments[TName], DossierClientOperationReturnOk[TName], DossierClientOperationReturnError[TName]>;
export type DossierClientMiddleware<TContext extends ClientContext> = Middleware<TContext, DossierClientOperation>;
export type JsonDossierClientOperationArgs<TName extends DossierClientOperationName = DossierClientOperationName> = DossierClientOperationArguments[TName];
export declare const DossierClientModifyingOperations: Readonly<Set<string>>;
export declare function createBaseDossierClient<TContext extends ClientContext, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient>(option: {
    context: TContext | ContextProvider<TContext>;
    pipeline: DossierClientMiddleware<TContext>[];
}): TClient;
export declare function executeJsonDossierClientOperation(client: DossierClient<Entity<string, object>, Component<string, object>>, operationName: LooseAutocomplete<DossierClientOperationName>, operationArgs: JsonDossierClientOperationArgs): PromiseResult<unknown, ErrorType>;
export declare function convertJsonDossierClientResult<TName extends DossierClientOperationName, TClient extends DossierClient<Entity<string, object>, Component<string, object>> = DossierClient>(operationName: TName, jsonResult: Result<unknown, ErrorType>): MethodReturnTypeWithoutPromise<TName, TClient>;
export {};