yrby-client 0.4.3 → 0.6.0

package/dist/cjs/document_element.js

@@ -0,0 +1,260 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YrbyDocumentElement = void 0;
+const document_session_js_1 = require("./document_session.js");
+const turbo_adapter_js_1 = require("./turbo_adapter.js");
+// Lets tests and SSR import this module where HTMLElement is undefined.
+const Base = (typeof HTMLElement === "undefined" ? class {
+} : HTMLElement);
+// Holds the application's own inert value while the element forces inert on.
+const INERT_ATTRIBUTE = "data-yrby-inert";
+let sharedConsumer;
+// Loads once per page. A failed import is cleared so a later attempt can retry it.
+function defaultConsumer() {
+    sharedConsumer ??= Promise.resolve().then(() => __importStar(require("@rails/actioncable"))).then(actioncable => actioncable.createConsumer())
+        .catch(error => { sharedConsumer = undefined; throw error; });
+    return sharedConsumer;
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise(r => { resolve = r; });
+    return { promise, resolve };
+}
+// Returns the yrby:error detail for a session that ended a lease. A block gets
+// a detail, and a discard gets undefined.
+function blockReport(session) {
+    return session.state === "blocked" ? { error: session.error, session } : undefined;
+}
+// The element binds when it is in the page, the Turbo adapter reports the page
+// as live, and it has a descriptor. It abandons an attempt synchronously,
+// because Turbo copies the page as soon as before-cache fires, and after a
+// retarget the editor has to stop writing to the old document before anything
+// else runs. Starting and advancing an attempt and handling every async result
+// all go through #settle, which runs after the current call stack and compares
+// what should be bound with what is.
+class YrbyDocumentElement extends Base {
+    /** Set before adding elements to use another consumer, such as AnyCable's. */
+    static consumer;
+    // refresh is read when the session is acquired and isn't part of the
+    // document's identity, so changing it doesn't rebind the editor.
+    static observedAttributes = ["grant", "name", "channel"];
+    #live = false; // false while Turbo is showing a cached copy of the page
+    #attempt;
+    // Key of the document whose session blocked or failed. The element won't retry
+    // it until the page renders again, the attributes change, or the element is
+    // re-inserted.
+    #stalledKey;
+    #unregister;
+    #settleQueued = false;
+    // Resolves when the current attempt first syncs. Abandoning the attempt replaces it.
+    #firstSync = deferred();
+    get session() {
+        // Treat a lease its session aborted as gone, even before settle runs.
+        const lease = this.#attempt?.lease;
+        return lease && !lease.signal.aborted ? lease.session : undefined;
+    }
+    get doc() { return this.session?.doc; }
+    get provider() { return this.session?.provider; }
+    /** Resolves after the current attempt's first sync. If the attempt is abandoned, its promise never resolves. */
+    get whenSynced() { return this.#firstSync.promise; }
+    connectedCallback() {
+        this.#stalledKey = undefined;
+        // A same-turn move keeps its attempt, so don't make a live editor inert.
+        if (!this.#attempt)
+            this.#holdInert();
+        this.#unregister ??= (0, turbo_adapter_js_1.registerDocumentMount)(this);
+        this.#requestSettle();
+    }
+    // Same-turn moves keep their binding, because settle checks isConnected afterwards.
+    disconnectedCallback() { this.#requestSettle(); }
+    attributeChangedCallback(_name, oldValue, newValue) {
+        if (oldValue === newValue)
+            return;
+        this.#stalledKey = undefined;
+        this.#abandon();
+        this.#requestSettle();
+    }
+    /** @internal Called by the Turbo adapter when the page is live. A new render also retries a stalled document. */
+    activate() {
+        this.#live = true;
+        this.#stalledKey = undefined;
+        this.#requestSettle();
+    }
+    /** @internal Called by the Turbo adapter when the page is cached or previewed. */
+    deactivate() {
+        this.#live = false;
+        this.#abandon();
+    }
+    /** Releases the editor lease. The session keeps any unsaved work. */
+    destroy() {
+        // Reset the adapter's last report. The next connection registers again and gets a new one.
+        this.#live = false;
+        // Clear it before the call, since the call can re-enter through a replacement registration.
+        const unregister = this.#unregister;
+        this.#unregister = undefined;
+        unregister?.();
+        this.#abandon();
+    }
+    #requestSettle() {
+        if (this.#settleQueued)
+            return;
+        this.#settleQueued = true;
+        queueMicrotask(() => this.#settle());
+    }
+    #settle() {
+        this.#settleQueued = false;
+        if (!this.isConnected) {
+            this.destroy();
+            return;
+        }
+        const descriptor = this.#descriptor();
+        // key is undefined when nothing should be bound, because the page is cached
+        // or the attributes don't name a document yet.
+        const key = this.#live && descriptor.grant && descriptor.name ? (0, document_session_js_1.documentKey)(descriptor) : undefined;
+        const attempt = this.#attempt;
+        if (attempt && attempt.key !== key) {
+            // Should not happen, since every change to these facts already abandons the attempt.
+            this.#abandon();
+            this.#requestSettle();
+            return;
+        }
+        if (key === undefined || key === this.#stalledKey)
+            return;
+        // Take the next step. An attempt starts, acquires a lease once the consumer
+        // loads, and announces once synced. If the attempt has ended, stall.
+        if (!attempt)
+            this.#start(key, descriptor);
+        else if (attempt.ended)
+            this.#stall(attempt.ended.detail);
+        else if (attempt.consumer && !attempt.lease)
+            this.#acquire(attempt, attempt.consumer);
+        else if (attempt.synced && !attempt.announced)
+            this.#announce(attempt);
+    }
+    #start(key, descriptor) {
+        const attempt = { key, descriptor };
+        this.#attempt = attempt;
+        Promise.resolve(_a.consumer ?? defaultConsumer()).then(consumer => { attempt.consumer = consumer; }, error => { attempt.ended = { detail: { error } }; }).then(() => this.#requestSettle());
+    }
+    #acquire(attempt, consumer) {
+        let lease;
+        try {
+            lease = document_session_js_1.DocumentSessionStore.for(consumer).acquire(attempt.descriptor);
+        }
+        catch (error) {
+            this.#stall({ error });
+            return;
+        }
+        attempt.lease = lease;
+        const { session } = lease;
+        // A blocked session keeps new leases for retry(), and its first sync may
+        // be long past, so an editor must not bind to it.
+        const blocked = blockReport(session);
+        if (blocked) {
+            attempt.ended = { detail: blocked };
+            this.#requestSettle();
+            return;
+        }
+        // The lease aborts when its session blocks or is discarded. Read the
+        // reason now, before anything retries the session.
+        lease.signal.addEventListener("abort", () => {
+            attempt.ended ??= { detail: blockReport(session) };
+            this.#requestSettle();
+        }, { once: true });
+        void session.whenSynced.then(() => {
+            attempt.synced = true;
+            this.#requestSettle();
+        });
+    }
+    #announce(attempt) {
+        attempt.announced = true;
+        const lease = attempt.lease;
+        const { session } = lease;
+        this.#restoreInert();
+        this.#firstSync.resolve();
+        this.dispatchEvent(new CustomEvent("yrby:synced", {
+            bubbles: true,
+            detail: { session, doc: session.doc, provider: session.provider, lease, signal: lease.signal },
+        }));
+    }
+    #stall(detail) {
+        this.#stalledKey = this.#attempt?.key;
+        this.#abandon();
+        if (detail)
+            this.dispatchEvent(new CustomEvent("yrby:error", { bubbles: true, detail }));
+    }
+    // Ends the current attempt. Releasing the lease runs editor cleanup, which
+    // may change attributes or move the element, and those changes only request
+    // a settle.
+    #abandon() {
+        const attempt = this.#attempt;
+        if (!attempt)
+            return;
+        this.#attempt = undefined;
+        this.#firstSync = deferred();
+        this.#holdInert();
+        attempt.lease?.release();
+    }
+    #descriptor() {
+        return {
+            channel: this.getAttribute("channel") || undefined,
+            grant: this.getAttribute("grant") || "",
+            name: this.getAttribute("name") || "",
+            refresh: this.getAttribute("refresh") || undefined,
+        };
+    }
+    // Stay inert until synced so nobody types into a document that isn't live yet.
+    // The application's own inert value goes in an attribute, which survives a
+    // Turbo cache clone, and is restored when the element is ready.
+    #holdInert() {
+        if (!this.hasAttribute(INERT_ATTRIBUTE))
+            this.setAttribute(INERT_ATTRIBUTE, String(this.inert));
+        this.inert = true;
+    }
+    #restoreInert() {
+        const saved = this.getAttribute(INERT_ATTRIBUTE);
+        if (saved === null)
+            return;
+        this.inert = saved === "true";
+        this.removeAttribute(INERT_ATTRIBUTE);
+    }
+}
+exports.YrbyDocumentElement = YrbyDocumentElement;
+_a = YrbyDocumentElement;
+if (typeof customElements !== "undefined" && !customElements.get("yrby-document")) {
+    customElements.define("yrby-document", YrbyDocumentElement);
+}

package/dist/cjs/document_session.d.ts

@@ -0,0 +1,62 @@
+import * as Y from "yjs";
+import { ActionCableProvider, type CableConsumer } from "./actioncable_provider.js";
+export interface DocumentDescriptor {
+    channel?: string;
+    grant: string;
+    name: string;
+    /** A same-origin URL that returns `{ "grant": "..." }` for this document. The session fetches it at most once per rejection. */
+    refresh?: string;
+}
+export type ResolvedDescriptor = Readonly<{
+    channel: string;
+    grant: string;
+    name: string;
+    refresh?: string;
+}>;
+export type DocumentSessionState = "open" | "blocked" | "closed";
+/** The identity of the document a descriptor names. Matching keys share a session. */
+export declare function documentKey(descriptor: DocumentDescriptor): string;
+declare const attachLease: unique symbol;
+declare const notifyStoreChange: unique symbol;
+/** Holds one consumer's sessions and emits "change" with the session in `detail`. */
+export declare class DocumentSessionStore extends EventTarget {
+    #private;
+    readonly consumer: CableConsumer;
+    static for(consumer: CableConsumer): DocumentSessionStore;
+    private constructor();
+    get sessions(): readonly DocumentSession[];
+    /** Acquire a lease on this document session, creating it on first use. */
+    acquire(input: DocumentDescriptor): DocumentLease;
+    [notifyStoreChange](session: DocumentSession): void;
+}
+/** A caller's hold on a session. Release it when you're done with the session. */
+export declare class DocumentLease {
+    #private;
+    readonly session: DocumentSession;
+    constructor(session: DocumentSession, onRelease: () => void);
+    /** Aborts when the lease ends, including when the session blocks or is discarded. */
+    get signal(): AbortSignal;
+    setPresence(state: Record<string, unknown> | null): void;
+    /** Runs editor cleanup synchronously, before the final check for pending work. */
+    release(): void;
+}
+export declare class DocumentSession {
+    #private;
+    readonly store: DocumentSessionStore;
+    readonly descriptor: ResolvedDescriptor;
+    private readonly remove;
+    readonly doc: Y.Doc;
+    readonly provider: ActionCableProvider;
+    /** Create and hold sessions through DocumentSessionStore.acquire. */
+    constructor(store: DocumentSessionStore, descriptor: ResolvedDescriptor, remove: () => void);
+    get error(): unknown;
+    get hasPending(): boolean;
+    get whenSynced(): Promise<void>;
+    get state(): DocumentSessionState;
+    [attachLease](): DocumentLease;
+    /** Reconnects with this session's current grant, which is the original one or the last one a refresh returned. */
+    retry(): void;
+    /** Closes the session and drops pending work. The application calls this explicitly, because an ordinary detach keeps pending work. */
+    discard(): void;
+}
+export {};

package/dist/cjs/document_session.js

@@ -0,0 +1,335 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentSession = exports.DocumentLease = exports.DocumentSessionStore = void 0;
+exports.documentKey = documentKey;
+// Holds a document for the application, independently of editors and page
+// navigation.
+//
+// A session remains open while an editor is attached or the server has not yet
+// acknowledged some of its edits, and it closes itself when neither is true.
+// When the server rejects the subscription, the session tries the descriptor's
+// refresh URL once if it has one. If there is no URL, the refresh fails, or the
+// server rejects the new grant, the session blocks. Blocking releases its
+// editors and keeps its queued work in memory until the application calls
+// retry() or discard().
+const Y = __importStar(require("yjs"));
+const random_1 = require("lib0/random");
+const actioncable_provider_js_1 = require("./actioncable_provider.js");
+// Each phase sets the state apps see, whether a new lease connects right away,
+// and which transitions are allowed. A new lease does not connect while the
+// session is blocked or waiting for a refreshed grant. Transitions that aren't
+// listed are ignored.
+const PHASES = {
+    open: { state: "open", connects: true, on: { refresh: "refreshing", block: "blocked", close: "closed" } },
+    refreshing: { state: "open", connects: false, on: { renew: "renewed", block: "blocked", close: "closed" } },
+    renewed: { state: "open", connects: true, on: { accept: "open", block: "blocked", close: "closed" } },
+    blocked: { state: "blocked", connects: false, on: { retry: "open", close: "closed" } },
+    closed: { state: "closed", connects: false, on: {} },
+};
+// Without a limit, a refresh request that never returns would leave the
+// session offline and stuck with its editors attached. After this long, the
+// session blocks.
+const REFRESH_TIMEOUT_MS = 15_000;
+const DEFAULT_CHANNEL = "Y::DocumentChannel";
+const stores = new WeakMap();
+/** The identity of the document a descriptor names. Matching keys share a session. */
+function documentKey(descriptor) {
+    return JSON.stringify([descriptor.channel || DEFAULT_CHANNEL, descriptor.grant, descriptor.name]);
+}
+// Only the factory may create a store for a consumer.
+const storeToken = Symbol("storeToken");
+// Not exported, so only the store can acquire leases.
+const attachLease = Symbol("attachLease");
+// Not exported, so only a session can publish store changes.
+const notifyStoreChange = Symbol("notifyStoreChange");
+/** Holds one consumer's sessions and emits "change" with the session in `detail`. */
+class DocumentSessionStore extends EventTarget {
+    consumer;
+    static for(consumer) {
+        let store = stores.get(consumer);
+        if (!store)
+            stores.set(consumer, store = new DocumentSessionStore(consumer, storeToken));
+        return store;
+    }
+    #sessions = new Map();
+    constructor(consumer, token) {
+        super();
+        this.consumer = consumer;
+        if (token !== storeToken)
+            throw new Error("Use DocumentSessionStore.for(consumer)");
+    }
+    get sessions() { return [...this.#sessions.values()]; }
+    /** Acquire a lease on this document session, creating it on first use. */
+    acquire(input) {
+        if (!input.grant || !input.name)
+            throw new Error("A document requires a grant and name");
+        // The refresh URL is not part of the identity. Matching tuples share a
+        // session, which renews with the URL from the first acquisition.
+        const descriptor = Object.freeze({
+            channel: input.channel || DEFAULT_CHANNEL,
+            grant: input.grant,
+            name: input.name,
+            ...(input.refresh ? { refresh: input.refresh } : {}),
+        });
+        const key = documentKey(descriptor);
+        let session = this.#sessions.get(key);
+        if (!session) {
+            session = new DocumentSession(this, descriptor, () => { this.#sessions.delete(key); });
+            this.#sessions.set(key, session);
+        }
+        return session[attachLease]();
+    }
+    [notifyStoreChange](session) {
+        this.dispatchEvent(new CustomEvent("change", { detail: session }));
+    }
+}
+exports.DocumentSessionStore = DocumentSessionStore;
+/** A caller's hold on a session. Release it when you're done with the session. */
+class DocumentLease {
+    session;
+    #controller = new AbortController();
+    #onRelease;
+    constructor(session, onRelease) {
+        this.session = session;
+        this.#onRelease = onRelease;
+    }
+    /** Aborts when the lease ends, including when the session blocks or is discarded. */
+    get signal() { return this.#controller.signal; }
+    setPresence(state) {
+        if (!this.signal.aborted)
+            this.session.provider.awareness.setLocalState(state);
+    }
+    /** Runs editor cleanup synchronously, before the final check for pending work. */
+    release() {
+        if (this.signal.aborted)
+            return;
+        this.#controller.abort();
+        this.#onRelease();
+    }
+}
+exports.DocumentLease = DocumentLease;
+// Application commands (acquire, retry, discard) take effect immediately.
+// Provider callbacks and lease releases record what happened and request a
+// settle, which runs after the current call stack finishes. Settle releases a
+// blocked session's leases, closes a session nobody needs, and notifies store
+// observers once.
+class DocumentSession {
+    store;
+    descriptor;
+    remove;
+    doc = new Y.Doc();
+    provider;
+    #lifecycle = { phase: "open" };
+    #leases = new Set();
+    // Leases held when the session blocked. Settle releases these and keeps any
+    // lease acquired while blocked for retry().
+    #retiring;
+    #error;
+    #dirty = false; // true until store observers are notified of the latest change
+    #settleQueued = false;
+    /** Create and hold sessions through DocumentSessionStore.acquire. */
+    constructor(store, descriptor, remove) {
+        this.store = store;
+        this.descriptor = descriptor;
+        this.remove = remove;
+        // The session uses one provider for its whole life. The provider queues
+        // edits while offline, so blocking and retrying only need to disconnect and
+        // connect.
+        this.provider = new actioncable_provider_js_1.ActionCableProvider(this.doc, store.consumer, descriptor.channel, {
+            grant: descriptor.grant,
+            name: descriptor.name,
+            // Ack sequence numbers are per session, not per record.
+            session_id: (0, random_1.uuidv4)(),
+        }, {
+            onError: (error, context) => {
+                if (context === "rejected")
+                    this.#rejected(error);
+                else if (this.state !== "closed") {
+                    this.#error = error;
+                    this.#changed();
+                }
+            },
+        });
+        this.provider.awareness.setLocalState(null); // no cursor until an editor sets one
+        this.provider.onStatusChange(({ status }) => {
+            if (this.state !== "open")
+                return;
+            // The server accepted the subscription, so a renewed grant is valid.
+            if (status === "connected" || status === "synced")
+                this.#transition("accept");
+            this.#changed();
+        });
+    }
+    get error() { return this.#error; }
+    get hasPending() { return this.provider.hasPending; }
+    get whenSynced() { return this.provider.whenSynced; }
+    get state() { return PHASES[this.#lifecycle.phase].state; }
+    [attachLease]() {
+        if (this.state === "closed")
+            throw new Error("Cannot acquire a closed document session");
+        const lease = new DocumentLease(this, () => this.#release(lease));
+        this.#leases.add(lease);
+        this.#changed();
+        if (PHASES[this.#lifecycle.phase].connects)
+            this.#connect();
+        return lease;
+    }
+    #release(lease) {
+        if (!this.#leases.delete(lease))
+            return;
+        this.#changed();
+        if (!this.#leases.size)
+            this.provider.awareness.setLocalState(null);
+    }
+    /** Reconnects with this session's current grant, which is the original one or the last one a refresh returned. */
+    retry() {
+        if (this.#transition("retry"))
+            this.#connect();
+    }
+    /** Closes the session and drops pending work. The application calls this explicitly, because an ordinary detach keeps pending work. */
+    discard() { this.#close(); }
+    #changed() {
+        this.#dirty = true;
+        if (this.#settleQueued)
+            return;
+        this.#settleQueued = true;
+        queueMicrotask(() => this.#settle());
+    }
+    #settle() {
+        this.#settleQueued = false;
+        // If editor cleanup retries or blocks during #enforce, #changed queues
+        // another settle to handle it.
+        this.#enforce();
+        if (!this.#dirty)
+            return;
+        this.#dirty = false;
+        this.store[notifyStoreChange](this);
+    }
+    #enforce() {
+        if (this.state === "closed")
+            return;
+        if (this.state === "blocked") {
+            const retiring = this.#retiring;
+            this.#retiring = undefined;
+            // Leave the queue alone until retry() or discard().
+            for (const lease of retiring ?? [])
+                lease.release();
+            return;
+        }
+        if (!this.#needed())
+            this.#close();
+    }
+    // Connect with the current grant, or resubscribe with a renewed one. The
+    // provider defers its own callbacks, so a failure here only blocks.
+    #connect(grant) {
+        try {
+            if (grant === undefined)
+                this.provider.connect();
+            else
+                this.provider.renew({ grant });
+        }
+        catch (error) {
+            this.#transition("block", error);
+        }
+    }
+    #needed() { return this.#leases.size > 0 || this.provider.hasPending; }
+    // The only method that changes the phase. It doesn't call out to other code,
+    // and #settle acts on the result.
+    #transition(event, error) {
+        const phase = PHASES[this.#lifecycle.phase].on[event];
+        if (!phase)
+            return false;
+        this.#lifecycle = { phase };
+        this.#retiring = phase === "blocked" ? [...this.#leases] : undefined;
+        if (event === "retry")
+            this.#error = undefined;
+        else if (event === "block")
+            this.#error = error;
+        this.#changed();
+        return true;
+    }
+    #close() {
+        if (!this.#transition("close"))
+            return;
+        // Leave the store first so editor cleanup below can acquire a new session.
+        this.remove();
+        for (const lease of [...this.#leases])
+            lease.release();
+        this.provider.destroy();
+        this.doc.destroy();
+    }
+    // Try the refresh URL once per rejection. Block if the server rejects again
+    // while refreshing or rejects the renewed grant.
+    #rejected(error) {
+        const url = this.descriptor.refresh;
+        if (url && this.#transition("refresh"))
+            void this.#refresh(url, this.#lifecycle);
+        else
+            this.#transition("block", error);
+    }
+    async #refresh(url, attempt) {
+        let grant;
+        try {
+            grant = await fetchGrant(url);
+        }
+        catch (error) {
+            if (this.#lifecycle === attempt)
+                this.#transition("block", error);
+            return;
+        }
+        // A retry, discard, or block during the request takes precedence over it.
+        if (this.#lifecycle !== attempt)
+            return;
+        if (this.#transition("renew"))
+            this.#connect(grant);
+    }
+}
+exports.DocumentSession = DocumentSession;
+/** Ask the application for a new grant. Resolves to the grant or throws. */
+async function fetchGrant(url) {
+    const response = await fetch(url, {
+        credentials: "same-origin",
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new Error(`grant refresh failed: ${response.status}`);
+    const body = await response.json();
+    const grant = body?.grant;
+    if (typeof grant !== "string" || !grant)
+        throw new Error("grant refresh returned no grant");
+    return grant;
+}

package/dist/cjs/index.d.ts

@@ -5,3 +5,5 @@ export type { YProtocolSessionOptions } from "./y_protocol_session.js";
 export { ActionCableProvider } from "./actioncable_provider.js";
 export type { ActionCableProviderOptions, ProviderStatus, StatusEvent, CableConsumer, CableSubscription, } from "./actioncable_provider.js";
 export { toBase64, fromBase64 } from "./base64.js";
+export { DocumentSessionStore } from "./document_session.js";
+export type { DocumentSession, DocumentLease, DocumentDescriptor, DocumentSessionState } from "./document_session.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromBase64 = exports.toBase64 = exports.ActionCableProvider = exports.MessageType = exports.YProtocolSession = exports.ReliableSync = void 0;
+exports.DocumentSessionStore = exports.fromBase64 = exports.toBase64 = exports.ActionCableProvider = exports.MessageType = exports.YProtocolSession = exports.ReliableSync = void 0;
 // Zero-dependency reliable-delivery core. Safe to import on its own.
 var reliable_sync_js_1 = require("./reliable_sync.js");
 Object.defineProperty(exports, "ReliableSync", { enumerable: true, get: function () { return reliable_sync_js_1.ReliableSync; } });
@@ -17,3 +17,6 @@ Object.defineProperty(exports, "ActionCableProvider", { enumerable: true, get: f
 var base64_js_1 = require("./base64.js");
 Object.defineProperty(exports, "toBase64", { enumerable: true, get: function () { return base64_js_1.toBase64; } });
 Object.defineProperty(exports, "fromBase64", { enumerable: true, get: function () { return base64_js_1.fromBase64; } });
+// Document sessions, leased by editors or held by headless workflows.
+var document_session_js_1 = require("./document_session.js");
+Object.defineProperty(exports, "DocumentSessionStore", { enumerable: true, get: function () { return document_session_js_1.DocumentSessionStore; } });