@brass-build/client 0.4.1 → 0.5.0

package/src/serializer.ts

@@ -2,30 +2,19 @@ import type { Document } from './documents.js';
 import type { ListHandle, MapHandle } from './handle-types.js';
 
 /**
- * A container read whole.
- *
- * The handles an app holds do not offer this: an app is handed its records
- * through `subscribe`, so a fire costs what changed rather than what the
- * document holds. A serializer is the other kind of caller. It runs detached,
- * with no subscription to have been fed by, and it needs the document once, so
- * it is handed a view that reads whole containers instead of being told to go
- * and fetch them.
+ * The document as a serializer sees it: the `Document` an app reads, walked
+ * with `entries()` / `values()`. Its `read()` is kept so a serializer written
+ * against it still compiles.
  */
 export interface StoredMap<T = unknown> extends MapHandle<T> {
+  /** @deprecated Walk the map with `entries()`. */
   read(): Record<string, T>;
 }
-
 export interface StoredList<T = unknown> extends ListHandle<T> {
+  /** @deprecated Walk the list with `values()`. */
   read(): T[];
 }
-
-/**
- * The document as a serializer sees it: the same containers, readable whole.
- *
- * A `Document` satisfies this, which is what keeps a serializer the platform
- * ships and one an app registers on one surface. The difference between them
- * is where they run, not what they are allowed to reach.
- */
+/** The document a serializer reads. */
 export interface StoredDocument {
   readonly id: string | null;
   map<T = unknown>(key: string): StoredMap<T>;
@@ -33,9 +22,8 @@ export interface StoredDocument {
 }
 
 // A per-app serializer that turns an app-owned (blob) document's records
-// back into the source file's bytes: the inverse of the parse the app ran
-// on `doc.sourceBlob()` when it opened the file. Register one at boot with
-// `Brass.registerSerializer`.
+// back into the source file's bytes: the inverse of the app's importer.
+// Register one at boot with `Brass.registerSerializer`.
 //
 // The platform invokes it, never the app: on a download from a hosted Brass
 // surface, the platform asks the running app to serialise, then handles