Class: DocStack

Defined in: packages/client/src/core/index.ts:69

The main entry point for the DocStack client library.

DocStack manages multiple ClientStack instances and provides a unified interface for database operations, authentication, and class/attribute creation.

The client emits a ready event when all stacks are initialized.

Example

// Initialize DocStack with a single database
const docstack = new DocStack({ name: 'my-app' });

// Wait for ready
docstack.addEventListener('ready', async () => {
    const stack = docstack.getStack('my-app');
    const taskClass = await stack.getClass('Task');
});

// Initialize with credentials for automatic authentication
const docstack = new DocStack({
    name: 'my-app',
    credentials: { username: 'admin', password: 'secret' }
});

Extends

• EventTarget

Constructors

Constructor

new DocStack(...config): DocStack;

Defined in: packages/client/src/core/index.ts:611

Creates a new DocStack client instance. Initializes all configured stacks asynchronously. Listen for the ready event to know when initialization is complete.

Parameters

Parameter	Type	Description
...config	StackConfig[]	One or more stack configurations

Returns

DocStack

Example

const docstack = new DocStack(
    { name: 'primary-db' },
    { name: 'backup-db' }
);

docstack.addEventListener('ready', () => {
    console.log('All stacks ready!');
});

Overrides

EventTarget.constructor

Properties

Property	Type	Default value	Description	Defined in
stacks	ClientStack[]	[]	Array of all initialized ClientStack instances.	packages/client/src/core/index.ts:77

Methods

addStack()

addStack(config): Promise<ClientStack>;

Defined in: packages/client/src/core/index.ts:147

Opens a stack and adds it to this instance.

Public because an application's set of databases is not always known at startup: a workspace joined at runtime needs its own database, and its own replication pair, without tearing down the stacks already open. Adding a stack that is already open returns the existing instance rather than opening a second handle on the same database.

Dispatches stack-added with the new stack in detail.

Parameters

Parameter	Type	Description
config	StackConfig	A stack name, or a full configuration object.

Returns

Promise<ClientStack>

The stack, initialized and ready.

Example

const stack = await docstack.addStack({ name: `ws-${workspace.slug}`, patches });
await stack.sync({ remote: () => driveFor(workspace) });

---

authenticateStack()

authenticateStack(name, credentials): Promise<AuthSessionProof>;

Defined in: packages/client/src/core/index.ts:432

Authenticates a user on a specific stack.

Parameters

Parameter	Type	Description
name	string	The stack name to authenticate against
credentials	ClientCredentials	The user's login credentials

Returns

Promise<AuthSessionProof>

The authentication session proof

Throws

Error if the stack is not found

Example

const proof = await docstack.authenticateStack('my-app', {
    username: 'user@example.com',
    password: 'password123'
});

---

cancelSync()

cancelSync(): void;

Defined in: packages/client/src/core/index.ts:348

Stops replication on every stack.

Returns

void

---

clearConnection()

clearConnection(conn): Promise<void>;

Defined in: packages/client/src/core/index.ts:466

Clears the connection data for a specific stack connection string.

Parameters

Parameter	Type	Description
conn	string	The connection string or name to clear.

Returns

Promise<void>

Throws

Error if the connection name is missing or the operation fails.

---

createAttribute()

createAttribute(
   stackName, 
   className, 
params): Promise<void>;

Defined in: packages/client/src/core/index.ts:561

Creates a new Attribute on a Class in the specified stack.

Parameters

Parameter	Type	Description
stackName	string	The name of the stack containing the class
className	string	The class to add the attribute to
params	{ config?: { }; description?: string; name: string; type: | "string" | "boolean" | "object" | "integer" | "date" | "decimal" | "foreign_key" | "enum" | "reference"; }	Attribute configuration
params.config?	{ }	-
params.description?	string	-
params.name	string	-
params.type	| "string" | "boolean" | "object" | "integer" | "date" | "decimal" | "foreign_key" | "enum" | "reference"	-

Returns

Promise<void>

Throws

Error if the stack or class is not found

Example

await docstack.createAttribute('my-app', 'Product', {
    name: 'price',
    type: 'number',
    description: 'Product price in cents'
});

---

createClass()

createClass(
   stackName, 
   name, 
config): Promise<void>;

Defined in: packages/client/src/core/index.ts:515

Creates a new Class in the specified stack.

Parameters

Parameter	Type	Description
stackName	string	The name of the stack to create the class in
name	string	The class name
config	{ description: string; type: string; }	Configuration with type and description
config.description	string	-
config.type	string	-

Returns

Promise<void>

Throws

Error if the stack is not found

Example

await docstack.createClass('my-app', 'Product', {
    type: 'class',
    description: 'Product catalog items'
});

---

export()

export(stackName): Promise<AllDocsResponse<{
}>>;

Defined in: packages/client/src/core/index.ts:489

Exports all documents from a stack.

Parameters

Parameter	Type	Description
stackName	string	The name of the stack to export

Returns

Promise<AllDocsResponse<{ }>>

All documents from the stack

Throws

Error if the stack is not found

---

getReadyState()

getReadyState(): boolean;

Defined in: packages/client/src/core/index.ts:444

Returns whether all stacks have been initialized.

Returns

boolean

true if ready, false otherwise

---

getStack()

getStack(name): ClientStack;

Defined in: packages/client/src/core/index.ts:412

Gets a stack by its name or connection string.

Parameters

Parameter	Type	Description
name	string	The stack name or connection identifier

Returns

ClientStack

The matching ClientStack, or undefined if not found

Example

const stack = docstack.getStack('my-app');
if (stack) {
    const users = await stack.query('SELECT * FROM User');
}

---

getStacks()

getStacks(): ClientStack[];

Defined in: packages/client/src/core/index.ts:394

Returns all initialized stacks.

Returns

ClientStack[]

Array of ClientStack instances

---

getSyncCoverage()

getSyncCoverage(): object;

Defined in: packages/client/src/core/index.ts:329

Which open stacks the current sync covers, and which it does not.

An idle stack and an unbound one are opposite problems, and getStatus() cannot tell them apart - the unbound one has no key at all. With no sync running, every open stack is unbound.

Returns

object

Name	Type	Defined in
bound	string[]	packages/client/src/core/index.ts:329
unbound	string[]	packages/client/src/core/index.ts:329

---

getSyncHandle()

getSyncHandle(): DocStackSyncHandle;

Defined in: packages/client/src/core/index.ts:341

Returns the handle from the last sync call, or null.

Returns

DocStackSyncHandle

---

removeStack()

removeStack(name, options?): Promise<boolean>;

Defined in: packages/client/src/core/index.ts:210

Closes a stack and drops it from this instance.

Closing cancels the stack's replication and releases its listeners; the data on disk is left alone unless destroy is set, which is what leaving a workspace for good looks like.

Dispatches stack-removed with the stack's name in detail.

Parameters

Parameter	Type	Description
name	string	The stack name or connection string.
options?	{ destroy?: boolean; }	destroy: true also deletes the underlying database.
options.destroy?	boolean	-

Returns

Promise<boolean>

true if a stack was removed, false if there was none by that name.

---

reset()

reset(): Promise<void>;

Defined in: packages/client/src/core/index.ts:451

Resets all stacks and re-initializes them. Useful for testing or clearing all data.

Returns

Promise<void>

---

resetAll()

resetAll(): Promise<void>;

Defined in: packages/client/src/core/index.ts:380

Resets all initialized stacks. This clears the data in all stacks managed by this DocStack instance.

Returns

Promise<void>

Throws

Error if the reset operation fails for any stack.

---

sync()

sync(options): Promise<DocStackSyncHandle>;

Defined in: packages/client/src/core/index.ts:247

Starts replication for every open stack against one transport.

The remote resolver is called once per stack, which is what makes a database-per-workspace application a single call rather than a loop the application has to keep in step with its own stack list.

Parameters

Parameter	Type	Description
options	DocStackSyncOptions	See DocStackSyncOptions. stacks narrows it to a subset.

Returns

Promise<DocStackSyncHandle>

A handle holding every stack's replication.

Example

const sync = await docstack.sync({
    remote: (stack) => new PouchDB(stack.name, { adapter: 'googledrive', accessToken }),
});
sync.addEventListener('status', () => render(sync.getStatus()));