app-storage

Import

Import

import * as api from "@fungi.computer/oyster/app-storage";

Exports

Kind	Export	Description
Ttype alias	AppStorageBinding	The App storage handle in env.APP_STORAGE.
Ttype alias	AppStorageWriter	Trusted backend writer: owners may also edit the Team layer; lifecycle has no member.
Ttype alias	AppStorageAdmission	Trusted live App admission, never supplied by the App or an HTTP body.
Ttype alias	AppStorageInstallationAdmission	Trusted installation lifecycle admission, with no member identity or private layer.
constconstant	appStorageSchemaStatements	SQLite tables, indexes and initial revision state used by the App storage owner.
fnfunction	appStorageWritable()	Whether writer may mutate scope; anything else is owner_required.
fnfunction	purgeAppStorageInCommit()	Called only inside the installation owner’s delete transaction.
fnfunction	purgeAppMemberStorageInCommit()	Called only inside the membership owner’s removal transaction.
fnfunction	createAppStorage()	One SQLite owner for scoped App values; its views bind the admitted member.

AppStorageBindingTtype alias

Signature

type AppStorageBinding = Readonly<{
  read: Promise<
    AppStorageResult<{
      value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
      source: Schema.Literals<readonly ["member", "team", "none"]>;
      team: Schema.NullOr<
        Schema.Struct<{
          value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
          revision: Schema.Int;
        }>
      >;
      member: Schema.NullOr<
        Schema.Struct<{
          value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
          revision: Schema.Int;
        }>
      >;
      canWriteTeam: Schema.Boolean;
    }>
  >;
  write: Promise<
    AppStorageResult<{
      revision: number;
    }>
  >;
  reset: Promise<
    AppStorageResult<{
      revision: number;
    }>
  >;
}>;

The App storage handle in env.APP_STORAGE.

---

AppStorageWriterTtype alias

Signature

type AppStorageWriter =
  | Readonly<{
      kind: "member";
      memberId: string;
      isOwner: boolean;
    }>
  | Readonly<{
      kind: "lifecycle";
      handler: string;
    }>;

Trusted backend writer: owners may also edit the Team layer; lifecycle has no member.

---

AppStorageAdmissionTtype alias

Signature

type AppStorageAdmission = Readonly<{
  address: string;
  appId: string;
  memberId: string;
  membershipVersion: number;
  isOwner: boolean;
  keys: readonly AppStorageKey[];
  assertCurrent: () => void;
}>;

Trusted live App admission, never supplied by the App or an HTTP body.

---

AppStorageInstallationAdmissionTtype alias

Signature

type AppStorageInstallationAdmission = Pick<
  AppStorageAdmission,
  "address" | "appId" | "keys" | "assertCurrent"
>;

Trusted installation lifecycle admission, with no member identity or private layer.

appStorageSchemaStatementsconstconstant

Signature

const appStorageSchemaStatements: readonly [
  "CREATE TABLE IF NOT EXISTS hub_app_storage (\n    address TEXT NOT NULL, app_id TEXT NOT NULL, key TEXT NOT NULL,\n    scope TEXT NOT NULL CHECK(scope IN ('team','member')), member_id TEXT NOT NULL, membership_version INTEGER NOT NULL,\n    value TEXT NOT NULL, revision INTEGER NOT NULL, bytes INTEGER NOT NULL,\n    PRIMARY KEY(address,app_id,key,scope,member_id,membership_version),\n    CHECK((scope='team' AND member_id='' AND membership_version=0) OR (scope='member' AND member_id<>'' AND membership_version>0))) STRICT",
  "CREATE INDEX IF NOT EXISTS hub_app_storage_member ON hub_app_storage(member_id) WHERE scope='member'",
  "CREATE TABLE IF NOT EXISTS hub_app_storage_clock (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL) STRICT",
  "INSERT OR IGNORE INTO hub_app_storage_clock VALUES(1,0)",
  "CREATE TABLE IF NOT EXISTS hub_app_storage_writes (address TEXT NOT NULL, member_id TEXT NOT NULL, membership_version INTEGER NOT NULL, started_at INTEGER NOT NULL, count INTEGER NOT NULL, PRIMARY KEY(address,member_id,membership_version)) STRICT",
];

SQLite tables, indexes and initial revision state used by the App storage owner.

appStorageWritable()fnfunction

Signature

function appStorageWritable(writer, scope): boolean;

Whether writer may mutate scope; anything else is owner_required.

Parameters

Parameter	Type
writer	AppStorageWriter
scope	"member" | "team"

Returns

boolean

---

purgeAppStorageInCommit()fnfunction

Signature

function purgeAppStorageInCommit(sql, address): void;

Called only inside the installation owner’s delete transaction.

Parameters

Parameter	Type
sql	Readonly<{ exec: (statement, …bindings) => WatchdogSqliteCursor; }>
address	string

Returns

void

---

purgeAppMemberStorageInCommit()fnfunction

Signature

function purgeAppMemberStorageInCommit(sql, memberId, throughVersion): void;

Called only inside the membership owner’s removal transaction.

Parameters

Parameter	Type
sql	Readonly<{ exec: (statement, …bindings) => WatchdogSqliteCursor; }>
memberId	string
throughVersion	number

Returns

void

---

createAppStorage()fnfunction

Signature

function createAppStorage(options): object;

One SQLite owner for scoped App values; its views bind the admitted member.

Parameters

Parameter	Type	Description
options	{ sql: Readonly<{ exec: (statement, …bindings) => WatchdogSqliteCursor; }>; now?: () => number; commit: <A>(body) => Effect<A, Error>; }	-
options.sql	Readonly<{ exec: (statement, …bindings) => WatchdogSqliteCursor; }>	The SQLite connection shared with installation and membership changes.
options.now?	() => number	Millisecond clock used for the existing per-principal write-rate limit.
options.commit	<A>(body) => Effect<A, Error>	Commit the supplied mutation atomically before publishing its invalidation.

Returns

Name	Type	Description
purgeInstallation()	(address) => void	Remove an installation’s values and write counters inside its delete transaction.
purgeMember()	(memberId, throughVersion) => void	Remove a member’s private values and counters through the revoked membership version.
openInstallation()	(authorize) => object	Bind a lifecycle view to fresh installation admission; only declared team layers are accessible.
open()	(authorize) => object	Bind a member view to live admission, declared keys and the current membership version.