js-bao-wss-client 2.2.0-alpha.12 → 2.2.0-alpha.14

package/README.md

@@ -123,9 +123,10 @@ const client = await initializeClient({
   appId: "my-app",
   models: [Task, Project],
 
-  // Yjs document persistence for Node.js
-  yjsPersistence: (docId, ydoc, { appId, userId }) => {
-    return new SqlitePersistence(docId, ydoc, {
+  // Yjs document persistence for Node.js. The first argument is the store
+  // name — see "What the first argument is" below.
+  yjsPersistence: (storeName, ydoc, { appId, userId }) => {
+    return new SqlitePersistence(storeName, ydoc, {
       dbPath: `${process.env.HOME}/.my-app/${appId}/${userId}/yjs.sqlite`
     });
   },
@@ -137,6 +138,34 @@ const { ydoc } = await client.documents.open("doc-123", {
 });
 ```
 
+**What the first argument is**
+
+The factory's first argument is the **store name** to persist this Yjs state
+under, not necessarily the document id. For an ordinary document, and for a
+large document (`documentFormat: 2`) that has not rotated yet, the two are the
+same value.
+
+A large document's Yjs state is an epoch *overlay* rather than the document
+itself, so once it rotates each epoch gets its own store name,
+`{documentId}@{epoch}`. A rotation attaches a provider for the fresh epoch and
+then clears the sealed one, so a factory that put both epochs under one name
+would lose every write made since the rotation to that clear. Keying your
+storage on the first argument — as the example above does — is correct for both
+kinds of document, and needs no change when a document grows large.
+
+The third argument carries the rest of what the store is for:
+
+| Field | Meaning |
+|-------|---------|
+| `appId` | The application id |
+| `userId` | The authenticated user, or `"anon"` |
+| `documentId` | The plain document id, without the epoch suffix |
+| `documentFormat` | `2` for a large document, `1` for an ordinary one — absent on the very first open of a document created elsewhere, whose format nothing local knows yet |
+| `epoch` | The epoch the store name is scoped to, or `null` when the name is the plain document id |
+
+Use `context.documentId` when you want to group every store belonging to one
+document; use the first argument whenever you are naming storage.
+
 **Why two storage systems?**
 
 - `storageConfig` → General key-value data (auth, cache, metadata)
@@ -1251,15 +1280,19 @@ console.log(result.documentId); // The created document ID
 console.log(result.alias.aliasKey); // "current-draft"
 console.log(result.alias.documentId); // Same as documentId
 
-// The alias create takes `documentFormat` too, so a large document can be
-// created with its alias atomically. The response carries `documentFormat: 2`
-// for a large document and omits the key for an ordinary one.
+// The alias create takes the whole create vocabulary — `tags`, `metadata` and
+// `documentFormat` — with the same meaning they have on `create()`: applied when
+// the call creates the document. The response echoes what it applied, and omits
+// `documentFormat` for an ordinary document.
 const ledger = await client.documents.createWithAlias({
   title: "Ledger",
   alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger", "q3"],
+  metadata: { owner: "finance" },
   documentFormat: 2,
 });
 console.log(ledger.documentFormat); // 2
+console.log(ledger.tags); // ["ledger", "q3"]
 
 // Attempting to create with an existing alias throws HTTP 409
 try {
@@ -1281,6 +1314,27 @@ try {
 
 Use `createWithAlias()` when you need guaranteed uniqueness based on an alias (e.g., "only one home page per app"). Use regular `create()` + `aliases.set()` when offline support is needed or when the document should be created regardless of alias conflicts.
 
+#### Get-or-Create with Alias
+
+When you want the document to exist rather than to be new — "this user's ledger" — `getOrCreateWithAlias()` is the idempotent form: the first call creates it, every later one returns the same document. It takes the same options, applied only when the call creates the document:
+
+```typescript
+const ledger = await client.documents.getOrCreateWithAlias({
+  title: "Ledger",
+  alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger"],
+  documentFormat: 2,
+});
+
+console.log(ledger.created); // true on the call that made it, false after
+console.log(ledger.documentFormat); // 2 either way
+console.log(ledger.tags); // ["ledger"] on the create; absent afterwards
+```
+
+A stated `documentFormat` is also a statement about a document the alias already names. If the stored format **differs**, the call is refused with `DOCUMENT_FORMAT_MISMATCH` (409) naming the document and both formats, and nothing is created — being handed an ordinary document when you asked for a large one is the mistake this route exists to prevent. If it agrees, the format is echoed. Omit it and an existing binding is answered exactly as it always was.
+
+> All three create routes refuse a top-level body key they do not read, with 400 `VALIDATION_FAILED` and a `details` entry naming it. The typed methods above send only keys the routes read; this reaches you only if you build a request body by hand.
+
 ### Manage Permissions
 
 ```typescript