@docstack/client 0.1.5 → 0.1.8

package/lib/core/sync/tenants.d.ts

@@ -0,0 +1,67 @@
+import type { ClassModel } from "@docstack/shared";
+import type { ClassFilterOptions } from "./class-filter.js";
+import type ClientStack from "../stack.js";
+/**
+ * Tenant scoping for replication channels.
+ *
+ * A tenant is a stack (ADR-0030). `Class.tenants` declares which tenant spaces a class
+ * belongs to - a static list, so partitioning and channel scopes are derivable before
+ * any data exists. This module compiles a channel's *entitlement* (the tenants it may
+ * see) into configuration the sync layer already understands: which stacks the channel
+ * is served at all, and a class filter for stacks holding a mix of declarations.
+ *
+ * The split matters (ADR-0030 §5): the *partition* is the datamodel's, but the
+ * *entitlement* is the serving side's to grant - it cannot come from the datamodel,
+ * because every application ships its own model and none is authoritative about the
+ * others' entitlements. Enforcement then rides the existing filter chain, which is a
+ * conjunction: a derived filter can only narrow what the declarations admit.
+ *
+ * The strongest grant here is the one that is not a filter at all: a stack outside the
+ * scope is simply never served, so its namespace is unreachable rather than filtered.
+ *
+ * @module
+ */
+/** A channel's entitlement, compiled into sync configuration. */
+export interface TenantScope {
+    /**
+     * Stacks this entitlement is served at all. A stack not listed is withheld
+     * structurally - no replication is started against it, which is a stronger grant
+     * than any filter.
+     */
+    stacks: string[];
+    /**
+     * Class rules per served stack, present only where the stack needs them: an
+     * `exclude` where classes declared for other tenants share an entitled stack, an
+     * `include` where a stack is served only because entitled classes live in it.
+     */
+    classes: Record<string, ClassFilterOptions>;
+}
+/**
+ * Normalizes a class model's tenant declaration.
+ *
+ * @param model - Any object carrying (or omitting) a `tenants` declaration.
+ * @returns The declared tenant names; empty for a tenant-neutral class.
+ */
+export declare const classTenants: (model: Partial<Pick<ClassModel, "tenants">> | null | undefined) => string[];
+/**
+ * Compiles an entitlement into the stacks it reaches and the class rules it needs.
+ *
+ * A stack is served when its name is an entitled tenant - a tenant *is* a stack - or
+ * when it holds at least one class declared for an entitled tenant. Within a served
+ * stack:
+ *
+ * - classes declared for an entitled tenant travel;
+ * - tenant-neutral classes follow their stack: they travel when the stack itself is the
+ *   entitled tenant, which is what keeps a datamodel with no declarations at today's
+ *   behavior exactly;
+ * - classes declared only for other tenants are excluded.
+ *
+ * Resolved once per call, the way the sync layer resolves ephemeral classes when a
+ * replication starts (ADR-0028): a declaration that changes later takes effect on the
+ * next `sync()`, never silently mid-stream.
+ *
+ * @param stacks - The candidate stacks, typically every open stack.
+ * @param entitlement - The tenant names this channel may see.
+ * @returns Which stacks to serve, and per-stack class rules where needed.
+ */
+export declare const deriveTenantScope: (stacks: ClientStack[], entitlement: string[]) => Promise<TenantScope>;

package/lib/index.d.ts

@@ -1,4 +1,41 @@
 import { DocStack } from "./core/index.js";
 export { ClientStack, Class, Domain, Attribute, Trigger, DocStack } from "./core/index.js";
-export type { AttributeType, DocstackReady, StackConfig, StackOptions } from "@docstack/shared";
+/**
+ * Running jobs unattended.
+ *
+ * `JobEngine` executes a job when asked; `JobScheduler` decides when to ask, under the
+ * constraints a client imposes — an app that is closed most of the time, timers that
+ * freeze, several devices holding replicas of the same `~Job`, and job content that
+ * replicates and is executable. It is mounted at `stack.jobScheduler` and started by the
+ * application, which names the jobs allowed to run with nobody watching.
+ */
+export { JobEngine, JobScheduler, JOB_SCHEDULE_DOC_ID, parseSchedule, nextOccurrence } from "./core/index.js";
+export type { SchedulerOptions, SchedulerHost, JobScheduleState, TickReport, SkipReason, ParsedSchedule, } from "./core/index.js";
+/**
+ * The sync layer: lifecycle, filtering, convergence state and the schema gate.
+ *
+ * Transport-agnostic on purpose - `remote` is whatever PouchDB database the
+ * application hands over, so DocStack never learns about Google Drive, Firestore or
+ * anything else, and no consumer pays for a transport it does not use.
+ */
+export { StackSyncHandle, DocStackSyncHandle, SyncSchemaMismatchError, SYNC_META_DOC_ID, readRemoteSchemaVersion, publishSchemaVersion, createReplicationFilter, isInternalDoc, resolveInternalClasses, createClassFilter, hasClassRules, DATA_MODEL_CLASSES, withFilterIdentity, describeFilter, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, StackWriteGuardError, StackLockedError, deriveKeyId, isEncryptedPayload, deriveTenantScope, classTenants, } from "./core/index.js";
+export { SYSTEM_SEEDED_DOC_IDS, collectQueryClasses } from "./core/index.js";
+export type { EncryptedPayload, ClassBuildOptions } from "./core/index.js";
+/**
+ * Moving application content between stacks, without the datamodel that describes it.
+ */
+export { CONTENT_EXPORT_FORMAT, META_CLASSES, isContentClassName, isContentDocument, isContentRelation, } from "./core/index.js";
+export type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport, ContentImportIssue, } from "./core/index.js";
+export type { SyncDirection, SyncState, SyncStatus, StackSyncOptions, DocStackSyncOptions, RemoteResolver, SyncMetaDoc, InternalDocFilterOptions, ClassFilterOptions, TenantScope, } from "./core/index.js";
+/**
+ * Document-modelling types, re-exported from `@docstack/shared`.
+ *
+ * These describe the values consumers have to construct themselves — most of all
+ * `Patch`, which `StackOptions.patches` asks for. `@docstack/shared` is an internal
+ * package, so surfacing them here is the only import path an application has.
+ *
+ * Note that `Document` shadows the DOM's global `Document` in whichever module imports
+ * it; alias it (`import type { Document as DocStackDocument }`) in code that needs both.
+ */
+export type { AttributeType, AttributeTypeConfig, AttributeModel, ClassModel, DomainModel, TriggerModel, Document, RelationDocument, Patch, SelectAST, UnionAST, ClientCredentials, DocstackReady, StackConfig, StackOptions, } from "@docstack/shared";
 export default DocStack;