@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/storage.md

@@ -0,0 +1,620 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / storage
+
+# storage
+
+## Classes
+
+### AppStorageError
+
+Thrown by the storage client when a read, write, reset, or watch is rejected by
+the host; `code` identifies why.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AppStorageError(code, options?): AppStorageError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                                                                                                                           |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code`     | \| `"unavailable"` \| `"invalid"` \| `"conflict"` \| `"too_large"` \| `"undeclared_key"` \| `"scope_not_declared"` \| `"owner_required"` \| `"quota_exceeded"` |
+| `options?` | `ErrorOptions`                                                                                                                                                 |
+
+###### Returns
+
+[`AppStorageError`](#appstorageerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code:
+  | "unavailable"
+  | "invalid"
+  | "conflict"
+  | "too_large"
+  | "undeclared_key"
+  | "scope_not_declared"
+  | "owner_required"
+  | "quota_exceeded";
+```
+
+## Type Aliases
+
+### ResolvedAppStorage
+
+```ts
+type ResolvedAppStorage = typeof resolvedAppStorageSchema.Type;
+```
+
+The resolved value for a storage key, as returned by `read`: the merged value,
+which layer it came from, the raw team/member layers, and whether this App may
+write to the team layer.
+
+---
+
+### AppStorageWrite
+
+```ts
+type AppStorageWrite = typeof appStorageWriteSchema.Type;
+```
+
+A validated write request for one storage key.
+
+---
+
+### AppStorageReset
+
+```ts
+type AppStorageReset = typeof appStorageResetSchema.Type;
+```
+
+A validated reset request for one storage key.
+
+---
+
+### AppStorageEvent
+
+```ts
+type AppStorageEvent = typeof appStorageEventSchema.Type;
+```
+
+A change-event payload identifying which App, key, scope, and resulting revision
+changed.
+
+---
+
+### AppStorageResult
+
+```ts
+type AppStorageResult<A> =
+  | Readonly<{
+      kind: "accepted";
+      value: A;
+    }>
+  | Readonly<{
+      kind: "rejected";
+      code: AppStorageError["code"];
+    }>;
+```
+
+The wire-level outcome of a storage operation: either an accepted value or a
+rejection carrying an [AppStorageError](#appstorageerror) code.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `A`            |
+
+---
+
+### AppStorageWatch
+
+```ts
+type AppStorageWatch = ReadonlyStore<ResolvedAppStorage> & Disposable & object;
+```
+
+A live subscription to one storage key's resolved value: read the current value,
+subscribe to changes, and close when done watching.
+
+#### Type Declaration
+
+| Name      | Type         | Description                                                  |
+| --------- | ------------ | ------------------------------------------------------------ |
+| `close()` | () => `void` | Stop watching and release the underlying event subscription. |
+
+---
+
+### AppStorage
+
+```ts
+type AppStorage = Readonly<{
+  read: Promise<{
+    value: Json;
+    source: "none" | "member" | "team";
+    team: {
+      value: Json;
+      revision: number;
+    } | null;
+    member: {
+      value: Json;
+      revision: number;
+    } | null;
+    canWriteTeam: boolean;
+  }>;
+  write: Promise<{
+    revision: number;
+  }>;
+  reset: Promise<{
+    revision: number;
+  }>;
+  watch: Promise<AppStorageWatch>;
+}>;
+```
+
+This App's storage client, scoped to its declared member/team data.
+
+---
+
+### AppStorageEventHandle
+
+```ts
+type AppStorageEventHandle = Disposable & object;
+```
+
+A live object capability backing one key's change-event stream, adapted to Fetch
+so it can drive an `EventSource`.
+
+#### Type Declaration
+
+| Name      | Type                                   | Description                                                     |
+| --------- | -------------------------------------- | --------------------------------------------------------------- |
+| `fetch()` | (`request`) => `Promise`\<`Response`\> | Forward one `EventSource` request to the host's event stream.   |
+| `close()` | () => `Promise`\<`void`\>              | Release the change-event stream's underlying object capability. |
+
+---
+
+### AppStorageWire
+
+```ts
+type AppStorageWire = object;
+```
+
+The raw wire contract this capability negotiates with the host, before
+client-side input validation and error unwrapping.
+
+#### Methods
+
+##### read()
+
+```ts
+read(key): Promise<AppStorageResult<{
+  value: Json;
+  source: "none" | "member" | "team";
+  team:   | {
+     value: Json;
+     revision: number;
+   }
+     | null;
+  member:   | {
+     value: Json;
+     revision: number;
+   }
+     | null;
+  canWriteTeam: boolean;
+}>>;
+```
+
+Read a key's resolved value over the wire; resolves with an accepted value or a
+rejection code.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+###### Returns
+
+`Promise`\<[`AppStorageResult`](#appstorageresult)\<\{ `value`: `Json`;
+`source`: `"none"` \| `"member"` \| `"team"`; `team`: \| \{ `value`: `Json`;
+`revision`: `number`; \} \| `null`; `member`: \| \{ `value`: `Json`; `revision`:
+`number`; \} \| `null`; `canWriteTeam`: `boolean`; \}\>\>
+
+##### write()
+
+```ts
+write(input): Promise<AppStorageResult<{
+  revision: number;
+}>>;
+```
+
+Write a key's value over the wire; resolves with the accepted revision or a
+rejection code.
+
+###### Parameters
+
+| Parameter       | Type                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- |
+| `input`         | \{ `key`: `string`; `scope`: `"member"` \| `"team"`; `basedOn`: `number` \| `null`; `value`: `Json`; \} |
+| `input.key`     | `string`                                                                                                |
+| `input.scope`   | `"member"` \| `"team"`                                                                                  |
+| `input.basedOn` | `number` \| `null`                                                                                      |
+| `input.value`   | `Json`                                                                                                  |
+
+###### Returns
+
+`Promise`\<[`AppStorageResult`](#appstorageresult)\<\{ `revision`: `number`;
+\}\>\>
+
+##### reset()
+
+```ts
+reset(input): Promise<AppStorageResult<{
+  revision: number;
+}>>;
+```
+
+Reset a key's value over the wire; resolves with the accepted revision or a
+rejection code.
+
+###### Parameters
+
+| Parameter       | Type                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------- |
+| `input`         | \{ `key`: `string`; `scope`: `"member"` \| `"team"`; `basedOn`: `number` \| `null`; \} |
+| `input.key`     | `string`                                                                               |
+| `input.scope`   | `"member"` \| `"team"`                                                                 |
+| `input.basedOn` | `number` \| `null`                                                                     |
+
+###### Returns
+
+`Promise`\<[`AppStorageResult`](#appstorageresult)\<\{ `revision`: `number`;
+\}\>\>
+
+##### openEvents()
+
+```ts
+openEvents(key): Promise<AppStorageEventHandle>;
+```
+
+Open the change-event stream for a key, as a Fetch-adapted handle.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+###### Returns
+
+`Promise`\<[`AppStorageEventHandle`](#appstorageeventhandle)\>
+
+## Variables
+
+### appStorageErrorCodes
+
+```ts
+const appStorageErrorCodes: readonly [
+  "invalid",
+  "undeclared_key",
+  "scope_not_declared",
+  "owner_required",
+  "too_large",
+  "quota_exceeded",
+  "conflict",
+  "unavailable",
+];
+```
+
+Storage error codes the host and client agree on: invalid input, an undeclared
+key, a scope this App never declared, a member-only action tried without a
+member, a value or quota that is too large, a write conflict, or a transient
+host failure.
+
+---
+
+### appStorageErrorCodeSchema
+
+```ts
+const appStorageErrorCodeSchema: Literals<
+  readonly [
+    "invalid",
+    "undeclared_key",
+    "scope_not_declared",
+    "owner_required",
+    "too_large",
+    "quota_exceeded",
+    "conflict",
+    "unavailable",
+  ]
+>;
+```
+
+Validates that a value is one of the known storage error codes.
+
+---
+
+### resolvedAppStorageSchema
+
+```ts
+const resolvedAppStorageSchema: Struct<{
+  value: Codec<Json, Json, never, never>;
+  source: Literals<readonly ["member", "team", "none"]>;
+  team: NullOr<
+    Struct<{
+      value: Codec<Json, Json, never, never>;
+      revision: Int;
+    }>
+  >;
+  member: NullOr<
+    Struct<{
+      value: Codec<Json, Json, never, never>;
+      revision: Int;
+    }>
+  >;
+  canWriteTeam: Boolean;
+}>;
+```
+
+Validates the resolved shape of a storage key: its merged value, which layer it
+came from, the raw team and member layers it was merged from, and whether this
+App may write to the team layer.
+
+---
+
+### appStorageWriteSchema
+
+```ts
+const appStorageWriteSchema: Struct<{
+  key: String;
+  scope: Literals<readonly ["team", "member"]>;
+  basedOn: NullOr<Int>;
+  value: Codec<Json, Json, never, never>;
+}>;
+```
+
+Validates a write request: the key, scope, value to store, and the revision it's
+conditioned on (`null` to write unconditionally).
+
+---
+
+### appStorageResetSchema
+
+```ts
+const appStorageResetSchema: Struct<{
+  key: String;
+  scope: Literals<readonly ["team", "member"]>;
+  basedOn: NullOr<Int>;
+}>;
+```
+
+Validates a reset request: the key, scope, and the revision it's conditioned on
+(`null` to reset unconditionally).
+
+---
+
+### appStorageRevisionSchema
+
+```ts
+const appStorageRevisionSchema: Struct<{
+  revision: Int;
+}>;
+```
+
+Validates a bare revision number returned after a write or reset.
+
+---
+
+### appStorageEventSchema
+
+```ts
+const appStorageEventSchema: Struct<{
+  appId: String;
+  key: String;
+  scope: Literals<readonly ["team", "member"]>;
+  revision: Int;
+}>;
+```
+
+Validates a change-event payload pushed when a storage key's value changes,
+naming the App, key, scope, and resulting revision.
+
+---
+
+### appStorageReadResultSchema
+
+```ts
+const appStorageReadResultSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"accepted">;
+      value: Struct<{
+        value: Codec<Json, Json, never, never>;
+        source: Literals<readonly ["member", "team", "none"]>;
+        team: NullOr<
+          Struct<{
+            value: Codec<Json, Json, never, never>;
+            revision: Int;
+          }>
+        >;
+        member: NullOr<
+          Struct<{
+            value: Codec<Json, Json, never, never>;
+            revision: Int;
+          }>
+        >;
+        canWriteTeam: Boolean;
+      }>;
+    }>,
+    Struct<{
+      kind: Literal<"rejected">;
+      code: Literals<
+        readonly [
+          "invalid",
+          "undeclared_key",
+          "scope_not_declared",
+          "owner_required",
+          "too_large",
+          "quota_exceeded",
+          "conflict",
+          "unavailable",
+        ]
+      >;
+    }>,
+  ]
+>;
+```
+
+Validates the wire result of a read: either an accepted resolved value or a
+rejection code.
+
+---
+
+### appStorageMutationResultSchema
+
+```ts
+const appStorageMutationResultSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"accepted">;
+      value: Struct<{
+        revision: Int;
+      }>;
+    }>,
+    Struct<{
+      kind: Literal<"rejected">;
+      code: Literals<
+        readonly [
+          "invalid",
+          "undeclared_key",
+          "scope_not_declared",
+          "owner_required",
+          "too_large",
+          "quota_exceeded",
+          "conflict",
+          "unavailable",
+        ]
+      >;
+    }>,
+  ]
+>;
+```
+
+Validates the wire result of a write or reset: either an accepted revision or a
+rejection code.
+
+---
+
+### appStorageBrokerReadResultSchema
+
+```ts
+const appStorageBrokerReadResultSchema: Union<readonly [Union<readonly [Struct<{
+  kind: Literal<"accepted">;
+  value: Struct<{
+     value: Codec<Json, Json, never, never>;
+     source: Literals<readonly ["member", "team", "none"]>;
+     team: NullOr<Struct<{
+        value: ...;
+        revision: ...;
+     }>>;
+     member: NullOr<Struct<{
+        value: ...;
+        revision: ...;
+     }>>;
+     canWriteTeam: Boolean;
+  }>;
+}>, Struct<{
+  kind: Literal<"rejected">;
+  code: Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+}>]>, Struct<{
+  error: String;
+}>]>;
+```
+
+The read result at a host broker, retaining its existing admission/failure
+reply.
+
+---
+
+### appStorageBrokerMutationResultSchema
+
+```ts
+const appStorageBrokerMutationResultSchema: Union<
+  readonly [
+    Union<
+      readonly [
+        Struct<{
+          kind: Literal<"accepted">;
+          value: Struct<{
+            revision: Int;
+          }>;
+        }>,
+        Struct<{
+          kind: Literal<"rejected">;
+          code: Literals<
+            readonly [
+              "invalid",
+              "undeclared_key",
+              "scope_not_declared",
+              "owner_required",
+              "too_large",
+              "quota_exceeded",
+              "conflict",
+              "unavailable",
+            ]
+          >;
+        }>,
+      ]
+    >,
+    Struct<{
+      error: String;
+    }>,
+  ]
+>;
+```
+
+The shared write/reset result at a host broker, including its existing failure
+reply.
+
+---
+
+### appStorage
+
+```ts
+const appStorage: CapabilityContract<AppStorage>;
+```
+
+This App's own declared data. The host seals App and member identities.
+
+---
+
+### appStorageKeyNameSchema
+
+```ts
+const appStorageKeyNameSchema: Schema.String;
+```
+
+Maintained grammar for one bounded key in an App's private storage.