Skip to content
Agar0.5.0
API reference

storage

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/agar/storage";

Exports

Section titled “Exports”
Kind Export Description
class AppStorageError Thrown by the storage client when a read, write, reset, or watch is rejected by the host; code identifies why.
type alias ResolvedAppStorage 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.
type alias AppStorageWrite A validated write request for one storage key.
type alias AppStorageReset A validated reset request for one storage key.
type alias AppStorageEvent A change-event payload identifying which App, key, scope, and resulting revision changed.
type alias AppStorageResult The wire-level outcome of a storage operation: either an accepted value or a rejection carrying an AppStorageError code.
type alias AppStorageWatch A live subscription to one storage key’s resolved value: read the current value, subscribe to changes, and close when done watching.
type alias AppStorage This App’s storage client, scoped to its declared member/team data.
type alias AppStorageEventHandle A live object capability backing one key’s change-event stream, adapted to Fetch so it can drive an EventSource.
type alias AppStorageWire The raw wire contract this capability negotiates with the host, before client-side input validation and error unwrapping.
constant appStorageErrorCodes 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.
constant appStorageErrorCodeSchema Validates that a value is one of the known storage error codes.
constant resolvedAppStorageSchema 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.
constant appStorageWriteSchema Validates a write request: the key, scope, value to store, and the expected revision of that layer (null requires the layer to be absent).
constant appStorageResetSchema Validates a reset request: the key, scope, and the revision it’s conditioned on (null requires the layer to be absent).
constant appStorageRevisionSchema Validates a bare revision number returned after a write or reset.
constant appStorageEventSchema Validates a change-event payload pushed when a storage key’s value changes, naming the App, key, scope, and resulting revision.
constant appStorageReadResultSchema Validates the wire result of a read: either an accepted resolved value or a rejection code.
constant appStorageMutationResultSchema Validates the wire result of a write or reset: either an accepted revision or a rejection code.
constant appStorageBrokerReadResultSchema The read result at a host broker, retaining its existing admission/failure reply.
constant appStorageBrokerMutationResultSchema The shared write/reset result at a host broker, including its existing failure reply.
constant appStorage This App’s own declared data. The host seals App and member identities.
constant appStorageKeyNameSchema Maintained grammar for one bounded key in an App’s private storage.

AppStorageErrorclass

Section titled “AppStorageError”

Thrown by the storage client when a read, write, reset, or watch is rejected by the host; code identifies why.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new AppStorageError(code, options?): AppStorageError;
Parameters
Section titled “Parameters”
Parameter Type
code | "unavailable" | "invalid" | "conflict" | "too_large" | "undeclared_key" | "scope_not_declared" | "owner_required" | "quota_exceeded"
options? ErrorOptions
Returns
Section titled “Returns”

AppStorageError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

code

Section titled “code”
Signature
readonly code:
  | "unavailable"
  | "invalid"
  | "conflict"
  | "too_large"
  | "undeclared_key"
  | "scope_not_declared"
  | "owner_required"
  | "quota_exceeded";

ResolvedAppStoragetype alias

Section titled “ResolvedAppStorage”
Signature
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.

AppStorageWritetype alias

Section titled “AppStorageWrite”
Signature
type AppStorageWrite = typeof appStorageWriteSchema.Type;

A validated write request for one storage key.

AppStorageResettype alias

Section titled “AppStorageReset”
Signature
type AppStorageReset = typeof appStorageResetSchema.Type;

A validated reset request for one storage key.

AppStorageEventtype alias

Section titled “AppStorageEvent”
Signature
type AppStorageEvent = typeof appStorageEventSchema.Type;

A change-event payload identifying which App, key, scope, and resulting revision changed.

AppStorageResulttype alias

Section titled “AppStorageResult”
Signature
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 code.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A

AppStorageWatchtype alias

Section titled “AppStorageWatch”
Signature
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

Section titled “Type Declaration”
Name Type Description
close() () => void Stop watching and release the underlying event subscription.

AppStoragetype alias

Section titled “AppStorage”
Signature
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.

AppStorageEventHandletype alias

Section titled “AppStorageEventHandle”
Signature
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

Section titled “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.

AppStorageWiretype alias

Section titled “AppStorageWire”
Signature
type AppStorageWire = object;

The raw wire contract this capability negotiates with the host, before client-side input validation and error unwrapping.

Methods

Section titled “Methods”

read()

Section titled “read()”
Signature
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
Section titled “Parameters”
Parameter Type
key string
Returns
Section titled “Returns”

Promise<AppStorageResult<{ value: Json; source: "none" | "member" | "team"; team: | { value: Json; revision: number; } | null; member: | { value: Json; revision: number; } | null; canWriteTeam: boolean; }>>

write()

Section titled “write()”
Signature
write(input): Promise<AppStorageResult<{
  revision: number;
}>>;

Write a key’s value over the wire; resolves with the accepted revision or a rejection code.

Parameters
Section titled “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
Section titled “Returns”

Promise<AppStorageResult<{ revision: number; }>>

reset()

Section titled “reset()”
Signature
reset(input): Promise<AppStorageResult<{
  revision: number;
}>>;

Reset a key’s value over the wire; resolves with the accepted revision or a rejection code.

Parameters
Section titled “Parameters”
Parameter Type
input { key: string; scope: "member" | "team"; basedOn: number | null; }
input.key string
input.scope "member" | "team"
input.basedOn number | null
Returns
Section titled “Returns”

Promise<AppStorageResult<{ revision: number; }>>

openEvents()

Section titled “openEvents()”
Signature
openEvents(key): Promise<AppStorageEventHandle>;

Open the change-event stream for a key, as a Fetch-adapted handle.

Parameters
Section titled “Parameters”
Parameter Type
key string
Returns
Section titled “Returns”

Promise<AppStorageEventHandle>

appStorageErrorCodesconstant

Section titled “appStorageErrorCodes”
Signature
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.

appStorageErrorCodeSchemaconstant

Section titled “appStorageErrorCodeSchema”
Signature
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.

resolvedAppStorageSchemaconstant

Section titled “resolvedAppStorageSchema”
Signature
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.

appStorageWriteSchemaconstant

Section titled “appStorageWriteSchema”
Signature
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 expected revision of that layer (null requires the layer to be absent).

appStorageResetSchemaconstant

Section titled “appStorageResetSchema”
Signature
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 requires the layer to be absent).

appStorageRevisionSchemaconstant

Section titled “appStorageRevisionSchema”
Signature
const appStorageRevisionSchema: Struct<{
  revision: Int;
}>;

Validates a bare revision number returned after a write or reset.

appStorageEventSchemaconstant

Section titled “appStorageEventSchema”
Signature
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.

appStorageReadResultSchemaconstant

Section titled “appStorageReadResultSchema”
Signature
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.

appStorageMutationResultSchemaconstant

Section titled “appStorageMutationResultSchema”
Signature
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.

appStorageBrokerReadResultSchemaconstant

Section titled “appStorageBrokerReadResultSchema”
Signature
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.

appStorageBrokerMutationResultSchemaconstant

Section titled “appStorageBrokerMutationResultSchema”
Signature
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.

appStorageconstant

Section titled “appStorage”
Signature
const appStorage: CapabilityContract<AppStorage>;

This App’s own declared data. The host seals App and member identities.

appStorageKeyNameSchemaconstant

Section titled “appStorageKeyNameSchema”
Signature
const appStorageKeyNameSchema: Schema.String;

Maintained grammar for one bounded key in an App’s private storage.