apps 0.0.1-beta.75 → 0.0.1-beta.76

package/types/app-cache/src/contracts/cache.d.ts

@@ -48,6 +48,17 @@ export declare const CacheAcquired: Schema.Struct<{
         readonly staleUntil: Schema.Finite;
     }>>;
     readonly lease: Schema.NullOr<Schema.String>;
+    /**
+     * The entries of the command's `reads`, in order, read in the same transaction as `entry`.
+     * Absent when the store did not read them: a store that predates them, or reads past the
+     * batch byte bound. The caller then reads them with a separate `read`.
+     */
+    readonly reads: Schema.optionalKey<Schema.$Array<Schema.NullOr<Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly version: Schema.String;
+        readonly freshUntil: Schema.Finite;
+        readonly staleUntil: Schema.Finite;
+    }>>>>;
 }>;
 /**
  * Publication requires the lease acquired against the previously observed version.
@@ -64,6 +75,11 @@ export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
     readonly refresh: Schema.Boolean;
     /** Claim only while the entry still has this version. Absent accepts the current one. */
     readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    /**
+     * Other keys to read in the same transaction, as `read` would, so a caller that needs them
+     * beside the entry makes one round trip. Reading them claims and changes nothing.
+     */
+    readonly reads: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, Schema.Struct<{
     readonly operation: Schema.Literal<"claim">;
     readonly key: Schema.String;

package/types/app-cache/src/index.d.ts

@@ -41,6 +41,23 @@ deadline?: number) => {
      * or wait for the lease owner.
      */
     get: <A>(options: CacheGet<A>) => Effect.Effect<A, unknown, never>;
+    /**
+     * `get`, also reading the keys of this scope that `keys` names in the same round trip. `keys`
+     * gets the entry's store key, which is unique to this scope and key, so a caller can remember
+     * what it read under it. `reads` holds their entries, undecoded and in order, when the value
+     * was read from the store; it is undefined when the value was loaded or the store did not read
+     * them, and the caller then reads what it still needs.
+     */
+    getWith: <A>(options: CacheGet<A>, keys: (key: string) => readonly Schema.Json[]) => Effect.Effect<{
+        value: A;
+        key: string;
+        reads: readonly ({
+            readonly value: Schema.Json;
+            readonly version: string;
+            readonly freshUntil: number;
+            readonly staleUntil: number;
+        } | null)[] | undefined;
+    }, unknown, never>;
     /** Force one awaited refresh without removing the retained value. Concurrent refreshes share a load. */
     revalidate: <A>(options: CacheGet<A>) => Effect.Effect<A, unknown, never>;
 };
@@ -60,6 +77,7 @@ export declare const holdLeases: (transport: CacheTransport) => Effect.Effect<{
         readonly key: string;
         readonly refresh: boolean;
         readonly version?: string | null;
+        readonly reads?: readonly string[];
     } | {
         readonly operation: "claim";
         readonly key: string;

package/types/apps/src/contracts/protocols/current.d.ts

@@ -3382,6 +3382,7 @@ export declare const current: {
             readonly key: Schema.String;
             readonly refresh: Schema.Boolean;
             readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly reads: Schema.optionalKey<Schema.$Array<Schema.String>>;
         }>, Schema.Struct<{
             readonly operation: Schema.Literal<"claim">;
             readonly key: Schema.String;

package/types/apps/src/implementation/cache.d.ts

@@ -1,7 +1,30 @@
 /** Bind the portable Effect cache to an app invocation's author API. */
 import { type Context } from "effect";
-import type { AppCache, HostCache } from "../contracts/cache.js";
+import type { AppCache, CacheGetOptions, HostCache } from "../contracts/cache.js";
 import type { ResolvedAccounts } from "../contracts/host.js";
+import type { JsonValue } from "../contracts/schema.js";
+/**
+ * Framework-only: `get` that also reads other keys of the same scope in its round trip to the
+ * store. Authored code never sees it; framework helpers use it when a cache provides it.
+ */
+export declare const getWithReads: unique symbol;
+/**
+ * A `get` value, the store key it was read under, and the stored values of the other keys when
+ * the value was read from the store. The values are not decoded: the caller decodes only those it
+ * uses. A key with no value reads `undefined`.
+ */
+export interface GetWithReads<A> {
+    readonly value: A;
+    /** The entry's store key, unique to the cache's scope and the key. */
+    readonly key: string;
+    /** Undefined when the value was loaded or the store did not read them: read them separately. */
+    readonly reads: readonly unknown[] | undefined;
+}
+/** The framework-only `get` an app's cache provides beside the author API. */
+export type CacheWithReads = AppCache & {
+    /** `keys` gets the entry's store key and names the other keys to read with it. */
+    readonly [getWithReads]?: <A>(options: CacheGetOptions<A>, keys: (key: string) => readonly JsonValue[]) => Promise<GetWithReads<A>>;
+};
 /** Missing host support is explicit on use; ordinary apps do not need cache support. */
 export declare const unavailableCache: HostCache;
 /** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */