@samebase/alchemy-convex 0.4.0 → 0.5.0

package/README.md

@@ -12,16 +12,19 @@ This is a community provider, maintained by [Samebase](https://samebase.com). Th
 follows the "Convex Plain" mode of [rjdellecese/confect#408](https://github.com/rjdellecese/confect/issues/408).
 [docs/design/convex-plane.md](docs/design/convex-plane.md) records the decisions.
 
-Status: pinned to `alchemy@2.0.0-beta.80` and Effect 4. Alchemy ships breaking changes between
+Status: pinned to `alchemy@2.0.0-beta.83` and Effect 4. Alchemy ships breaking changes between
 betas; upgrade this package and Alchemy together. A live test runs the full sequence with the real
 Convex CLI: create, push, no-op, change, preview, deploy keys alone, and destroy.
 
 ## Install
 
 ```sh
-pnpm add -D @samebase/alchemy-convex alchemy@2.0.0-beta.80 effect@^4.0.0 @effect/platform-node@^4.0.0 convex
+pnpm add -D @samebase/alchemy-convex alchemy@2.0.0-beta.83 effect@^4.0.0 @effect/platform-node@^4.0.0 convex
 ```
 
+Use one version for `effect` and for each `@effect/*` package. A mix fails at load time, such as
+`@effect/platform-node-shared` 4.0.5 next to `effect` 4.0.3.
+
 ## Example
 
 ```ts
@@ -87,6 +90,27 @@ reads them through the stack's config provider (process env, `.env`, stack secre
 A key that does not fit the deployment is not used: the provider uses the access token. To pass
 values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey }))`.
 
+## State in Convex
+
+`state: Convex.state()` keeps the Alchemy state of every stage in the production deployment of the
+project, so the stack needs no Cloudflare token.
+[docs/design/convex-state.md](docs/design/convex-state.md) records the decisions.
+
+1. Mount the state component in `convex/convex.config.ts` with its default name:
+
+   ```ts
+   import alchemyState from "@samebase/alchemy-convex/convex.config";
+   app.use(alchemyState);
+   ```
+
+2. Set `CONVEX_STATE_DEPLOY_KEY` in every run, a preview run too, to a production deploy key. A key
+   with only the actions `deployment:data:view` and `deployment:data:write` is sufficient.
+
+The first run starts with empty state, keeps it in memory until `Convex.Deployment` has pushed the
+component, and then writes it. A run whose push does not mount the component fails at the end.
+Rows are in the `alchemyState` component tables `resources` and `outputs` in the dashboard. The
+store has no lock: run one deploy of a stage at a time, such as with a CI concurrency group.
+
 ## Resources
 
 - `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its

package/lib/index.d.ts

@@ -7,6 +7,7 @@ import { Resource } from "alchemy";
 import * as Provider from "alchemy/Provider";
 import "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import { State, StateStoreError } from "alchemy/State";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
 interface ResolvedCredentials {
@@ -24,15 +25,15 @@ interface CredentialsService {
   readonly deployKey: Effect.Effect<Redacted.Redacted<string> | undefined>;
 }
 declare const Credentials_base: Context.ServiceClass<Credentials, "@samebase/alchemy-convex/Credentials", CredentialsService>;
-declare class Credentials extends Credentials_base {}
+export declare class Credentials extends Credentials_base {}
 /** Environment variable for the access token, read by {@link fromConfig}. */
-declare const ACCESS_TOKEN_ENV = "CONVEX_ACCESS_TOKEN";
+export declare const ACCESS_TOKEN_ENV = "CONVEX_ACCESS_TOKEN";
 /** Environment variable for the deploy key, read by {@link fromConfig}. The Convex CLI reads the same name. */
-declare const DEPLOY_KEY_ENV = "CONVEX_DEPLOY_KEY";
+export declare const DEPLOY_KEY_ENV = "CONVEX_DEPLOY_KEY";
 declare const CredentialsError_base: Schema.Class<CredentialsError, Schema.TaggedStruct<"CredentialsError", {
   readonly reason: Schema.String;
 }>, import("effect/Cause").YieldableError>;
-declare class CredentialsError extends CredentialsError_base {}
+export declare class CredentialsError extends CredentialsError_base {}
 /**
  * Default resolution through the stack ConfigProvider (process env, `.env`,
  * stack secrets): `CONVEX_ACCESS_TOKEN`, then the Convex CLI login on this
@@ -41,9 +42,9 @@ declare class CredentialsError extends CredentialsError_base {}
  * deploy key when the stack pushes to deployments that exist, and the access
  * token when the stack also creates projects or deployments.
  */
-declare const fromConfig: () => Layer.Layer<Credentials>;
+export declare const fromConfig: () => Layer.Layer<Credentials>;
 /** Explicit values, for tests or callers that already hold them. */
-declare const fromValues: (values: {
+export declare const fromValues: (values: {
   readonly accessToken?: Redacted.Redacted<string>;
   readonly deployKey?: Redacted.Redacted<string>;
 }) => Layer.Layer<Credentials>;
@@ -68,7 +69,7 @@ declare const ConvexApiError_base: Schema.Class<ConvexApiError, Schema.TaggedStr
  * `status` (404 means absent for read and delete), so the class is load
  * bearing, not decorative.
  */
-declare class ConvexApiError extends ConvexApiError_base {}
+export declare class ConvexApiError extends ConvexApiError_base {}
 interface ManagementApiService {
   /** Run one management call with the resolved credentials. */
   readonly request: <T>(operation: string, run: (client: ManagementClient) => Promise<FetchResult<T>>) => Effect.Effect<T, ConvexApiError>;
@@ -93,17 +94,17 @@ interface ManagementApiService {
   readonly withToken: (token: Redacted.Redacted<string>) => ManagementApiService;
 }
 declare const ManagementApi_base: Context.ServiceClass<ManagementApi, "@samebase/alchemy-convex/ManagementApi", ManagementApiService>;
-declare class ManagementApi extends ManagementApi_base {}
+export declare class ManagementApi extends ManagementApi_base {}
 //#endregion
 //#region src/Providers.d.ts
 declare const Providers_base: Provider.ProviderCollection<Providers, "Convex">;
-declare class Providers extends Providers_base {}
+export declare class Providers extends Providers_base {}
 /**
  * The Convex resource providers. Pass a credentials layer to override the
  * default lookup (`CONVEX_ACCESS_TOKEN`, then the Convex CLI login, and
  * `CONVEX_DEPLOY_KEY`).
  */
-declare const providers: (credentials?: Layer.Layer<Credentials>) => Layer.Layer<Providers, never, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;
+export declare const providers: (credentials?: Layer.Layer<Credentials>) => Layer.Layer<Providers, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("effect/process/ChildProcessSpawner").ChildProcessSpawner>;
 //#endregion
 //#region src/Push.d.ts
 /** A value of the `env` prop: a string, or a secret such as `Config.Redacted("AUTH_SECRET")`. */
@@ -135,14 +136,14 @@ declare const ConvexCliNotFound_base: Schema.Class<ConvexCliNotFound, Schema.Tag
   readonly cwd: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** No `convex` package resolves from the app directory. */
-declare class ConvexCliNotFound extends ConvexCliNotFound_base {
+export declare class ConvexCliNotFound extends ConvexCliNotFound_base {
   get message(): string;
 }
 declare const ConvexAppNotFound_base: Schema.Class<ConvexAppNotFound, Schema.TaggedStruct<"ConvexAppNotFound", {
   readonly source: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** No directory at or above the parent of `source` has a package.json. */
-declare class ConvexAppNotFound extends ConvexAppNotFound_base {
+export declare class ConvexAppNotFound extends ConvexAppNotFound_base {
   get message(): string;
 }
 declare const CodePushFailed_base: Schema.Class<CodePushFailed, Schema.TaggedStruct<"CodePushFailed", {
@@ -152,7 +153,7 @@ declare const CodePushFailed_base: Schema.Class<CodePushFailed, Schema.TaggedStr
   readonly outputTail: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** The Convex CLI failed, or exited 0 without the deployment URL. The output tail never contains the key. */
-declare class CodePushFailed extends CodePushFailed_base {
+export declare class CodePushFailed extends CodePushFailed_base {
   get message(): string;
 }
 declare const PushTargetMismatch_base: Schema.Class<PushTargetMismatch, Schema.TaggedStruct<"PushTargetMismatch", {
@@ -160,7 +161,7 @@ declare const PushTargetMismatch_base: Schema.Class<PushTargetMismatch, Schema.T
   readonly actual: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** The CLI pushed to another deployment than the one of the resource. Checked after the push. */
-declare class PushTargetMismatch extends PushTargetMismatch_base {
+export declare class PushTargetMismatch extends PushTargetMismatch_base {
   get message(): string;
 }
 declare const VariablesOwnedBySomeoneElse_base: Schema.Class<VariablesOwnedBySomeoneElse, Schema.TaggedStruct<"VariablesOwnedBySomeoneElse", {
@@ -168,18 +169,18 @@ declare const VariablesOwnedBySomeoneElse_base: Schema.Class<VariablesOwnedBySom
   readonly names: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /** Variables in `env` exist on the deployment with other values, and adoption is off. */
-declare class VariablesOwnedBySomeoneElse extends VariablesOwnedBySomeoneElse_base {
+export declare class VariablesOwnedBySomeoneElse extends VariablesOwnedBySomeoneElse_base {
   get message(): string;
 }
 declare const EnvironmentNeedsDeployKey_base: Schema.Class<EnvironmentNeedsDeployKey, Schema.TaggedStruct<"EnvironmentNeedsDeployKey", {
   readonly deployment: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** A preview deploy key cannot set variables: the deployment API takes only a deploy key of the deployment. */
-declare class EnvironmentNeedsDeployKey extends EnvironmentNeedsDeployKey_base {
+export declare class EnvironmentNeedsDeployKey extends EnvironmentNeedsDeployKey_base {
   get message(): string;
 }
 /** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
-declare const parseDeployOutput: (text: string) => {
+export declare const parseDeployOutput: (text: string) => {
   url: string;
   deploymentName: string;
 } | undefined;
@@ -233,8 +234,8 @@ interface DeploymentAttributes extends DeploymentTarget {
   /** The names of the `env` variables that this resource set on the deployment, sorted. */
   readonly envNames: readonly string[];
 }
-type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
-declare const Deployment: import("alchemy").ResourceClass<Deployment>;
+export type Deployment = Resource<"Convex.Deployment", DeploymentProps, DeploymentAttributes, never, Providers>;
+export declare const Deployment: import("alchemy").ResourceClass<Deployment>;
 declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChange, Schema.TaggedStruct<"DeploymentIdentityChange", {
   /** Name of the deployment in state, such as `happy-animal-123`. */
   readonly deployment: Schema.String;
@@ -243,14 +244,14 @@ declare const DeploymentIdentityChange_base: Schema.Class<DeploymentIdentityChan
   readonly requested: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** The props name another deployment than the one in state. */
-declare class DeploymentIdentityChange extends DeploymentIdentityChange_base {
+export declare class DeploymentIdentityChange extends DeploymentIdentityChange_base {
   get message(): string;
 }
 declare const ProductionDeploymentNotFound_base: Schema.Class<ProductionDeploymentNotFound, Schema.TaggedStruct<"ProductionDeploymentNotFound", {
   readonly projectId: Schema.Number;
 }>, import("effect/Cause").YieldableError>;
 /** The project has no default production deployment for a `prod` resource to take over. */
-declare class ProductionDeploymentNotFound extends ProductionDeploymentNotFound_base {
+export declare class ProductionDeploymentNotFound extends ProductionDeploymentNotFound_base {
   get message(): string;
 }
 declare const AmbiguousDeployment_base: Schema.Class<AmbiguousDeployment, Schema.TaggedStruct<"AmbiguousDeployment", {
@@ -260,7 +261,7 @@ declare const AmbiguousDeployment_base: Schema.Class<AmbiguousDeployment, Schema
   readonly deployments: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /** More than one deployment of the project has the name, so the lookup cannot choose one. */
-declare class AmbiguousDeployment extends AmbiguousDeployment_base {
+export declare class AmbiguousDeployment extends AmbiguousDeployment_base {
   get message(): string;
 }
 //#endregion
@@ -290,15 +291,15 @@ interface ProjectAttributes {
   readonly prodDeploymentName: string | undefined;
   readonly prodDeploymentUrl: string | undefined;
 }
-type Project = Resource<"Convex.Project", ProjectProps, ProjectAttributes, never, Providers>;
-declare const Project: import("alchemy").ResourceClass<Project>;
+export type Project = Resource<"Convex.Project", ProjectProps, ProjectAttributes, never, Providers>;
+export declare const Project: import("alchemy").ResourceClass<Project>;
 declare const ProjectTeamChange_base: Schema.Class<ProjectTeamChange, Schema.TaggedStruct<"ProjectTeamChange", {
   readonly projectId: Schema.Number;
   readonly teamId: Schema.Number;
   readonly requestedTeamId: Schema.Number;
 }>, import("effect/Cause").YieldableError>;
 /** The props change the team of an existing project. Convex cannot move a project. */
-declare class ProjectTeamChange extends ProjectTeamChange_base {
+export declare class ProjectTeamChange extends ProjectTeamChange_base {
   get message(): string;
 }
 declare const ProjectDeploymentChange_base: Schema.Class<ProjectDeploymentChange, Schema.TaggedStruct<"ProjectDeploymentChange", {
@@ -311,7 +312,7 @@ declare const ProjectDeploymentChange_base: Schema.Class<ProjectDeploymentChange
  * The props change `deploymentType` or `deploymentRegion` of an existing
  * project. Convex uses them only when it creates the project.
  */
-declare class ProjectDeploymentChange extends ProjectDeploymentChange_base {
+export declare class ProjectDeploymentChange extends ProjectDeploymentChange_base {
   get message(): string;
 }
 declare const AmbiguousProject_base: Schema.Class<AmbiguousProject, Schema.TaggedStruct<"AmbiguousProject", {
@@ -320,14 +321,14 @@ declare const AmbiguousProject_base: Schema.Class<AmbiguousProject, Schema.Tagge
   readonly projectIds: Schema.$Array<Schema.Number>;
 }>, import("effect/Cause").YieldableError>;
 /** More than one project in the team has the name, so the lookup cannot choose one. */
-declare class AmbiguousProject extends AmbiguousProject_base {
+export declare class AmbiguousProject extends AmbiguousProject_base {
   get message(): string;
 }
 declare const CreatedProjectNotFound_base: Schema.Class<CreatedProjectNotFound, Schema.TaggedStruct<"CreatedProjectNotFound", {
   readonly projectId: Schema.Number;
 }>, import("effect/Cause").YieldableError>;
 /** Convex answered a create call but then did not return the project. */
-declare class CreatedProjectNotFound extends CreatedProjectNotFound_base {
+export declare class CreatedProjectNotFound extends CreatedProjectNotFound_base {
   get message(): string;
 }
 declare const ProjectNotFound_base: Schema.Class<ProjectNotFound, Schema.TaggedStruct<"ProjectNotFound", {
@@ -335,9 +336,20 @@ declare const ProjectNotFound_base: Schema.Class<ProjectNotFound, Schema.TaggedS
   readonly slug: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** No project in the team has the slug. A `slug` resource never creates one. */
-declare class ProjectNotFound extends ProjectNotFound_base {
+export declare class ProjectNotFound extends ProjectNotFound_base {
   get message(): string;
 }
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, type DeploymentAttributes, DeploymentIdentityChange, type DeploymentProps, type DeploymentRegion, type EnvValue, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, type ProjectAttributes, ProjectDeploymentChange, ProjectNotFound, type ProjectProps, ProjectTeamChange, Providers, PushTargetMismatch, type Source, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers };
+//#region src/State.d.ts
+/** Environment variable with the deploy key of the deployment that holds the state. */
+export declare const STATE_DEPLOY_KEY_ENV = "CONVEX_STATE_DEPLOY_KEY";
+/**
+ * Alchemy state in the alchemyState component of the deployment that the
+ * deploy key in CONVEX_STATE_DEPLOY_KEY names: the production deployment of
+ * the project. The key needs the actions `deployment:data:view` and
+ * `deployment:data:write`.
+ */
+export declare const state: () => Layer.Layer<State>;
+//#endregion
+export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, Source };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts"],"mappings":";;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;cAGhC,oBAAoB;;cAKpB;;cAGA;;;;cAOA,yBAAyB;;;;;;;;;cAiCzB,kBAAiB,MAAM,MAAM;;cA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;cAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;cAM/C,sBAAsB;;;;cClFtB,kBAAkB;;;;;;cAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,+DAAA,kDAAA,mCAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;cA2BF,0BAA0B;MAIxB;;;;;;cAMF,0BAA0B;MAIxB;;;;;;;;;cAMF,uBAAuB;MAMrB;;;;;;;cAQF,2BAA2B;MAIzB;;;;;;;cAMF,oCAAoC;MAIlC;;;;;;cAMF,kCAAkC;MAIhC;;;cAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;KAGC,aAAa,8BAEvB,iBACA,6BAEA;cAEW,8BAAU,cAAA;;;;;;;;;cAKV,iCAAiC;MAU/B;;;;;;cAMF,qCAAqC;MAInC;;;;;;;;;cAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;KAGC,UAAU,2BAA2B,cAAc,0BAA0B;cAC5E,2BAAO,cAAA;;;;;;;cAGP,0BAA0B;MAIxB;;;;;;;;;;;;cASF,gCAAgC;MAS9B;;;;;;;;cAOF,yBAAyB;MAKvB;;;;;;cAMF,+BAA+B;MAI7B;;;;;;;cAMF,wBAAwB;MAItB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts","../src/State.ts"],"mappings":";;;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBA2BF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB;;;;;qBC7EF;;;;;;;qBAgQA,aAAY,MAAM,MAAM"}

package/lib/index.js

@@ -25,6 +25,7 @@ import { hashDirectory } from "alchemy/Command/Memo";
 import * as Clock from "effect/Clock";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as Stream from "effect/Stream";
+import { InMemoryService, STATE_STORE_VERSION, State, StateStoreError, encodeState, reviveState } from "alchemy/State";
 //#region src/Credentials.ts
 var Credentials = class extends Context.Service()("@samebase/alchemy-convex/Credentials") {};
 /** Environment variable for the access token, read by {@link fromConfig}. */
@@ -1256,6 +1257,191 @@ var Providers = class extends Provider.ProviderCollection()("Convex") {};
 */
 const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.orDie);
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers };
+//#region src/State.ts
+/** Environment variable with the deploy key of the deployment that holds the state. */
+const STATE_DEPLOY_KEY_ENV = "CONVEX_STATE_DEPLOY_KEY";
+/** The component path of alchemyState in the app: its default name. */
+const COMPONENT_PATH = "alchemyState";
+/** The body of POST /api/function and /api/query, with HTTP 200 or 560 for a function error. */
+const Reply = Schema.Union([Schema.Struct({
+	status: Schema.Literal("success"),
+	value: Schema.Unknown
+}), Schema.Struct({
+	status: Schema.Literal("error"),
+	errorMessage: Schema.String
+})]);
+/** The value of `_system/frontend/components:list`: the root has path "", a removed mount is "unmounted". */
+const Components = Schema.Array(Schema.Struct({
+	path: Schema.String,
+	state: Schema.String
+}));
+const failure = (message) => new StateStoreError({ message: `Convex state: ${message}` });
+/** No reply, HTTP 429, or HTTP 5xx: a new attempt can succeed. Every call of the store is idempotent. */
+const isTransient = (error) => error.http !== void 0 && (error.http.status === void 0 || error.http.status === 429 || error.http.status >= 500);
+const post = (url, headers, body) => Effect.tryPromise({
+	try: () => fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...headers
+		},
+		body: JSON.stringify(body)
+	}),
+	catch: () => new StateStoreError({
+		message: `Convex state: POST ${url} failed`,
+		http: {}
+	})
+}).pipe(Effect.flatMap((response) => response.ok || response.status === 560 ? Effect.tryPromise({
+	try: () => response.json(),
+	catch: () => failure(`${url} gave no JSON`)
+}) : Effect.fail(new StateStoreError({
+	message: `Convex state: POST ${url} failed with HTTP ${response.status}`,
+	http: { status: response.status }
+}))), Effect.retry({
+	while: isTransient,
+	schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+	times: 5
+}));
+const decode = (schema, what) => (value) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => failure(`bad ${what}`)));
+/**
+* The deployment URL of a deploy key. The Convex CLI makes the same unofficial
+* call for every deploy key (convex 1.46 `cli/lib/deploymentSelection.js`).
+*/
+const urlForKey = (key) => post("https://api.convex.dev/api/deployment/url_for_key", {}, { deployKey: Redacted.value(key) }).pipe(Effect.flatMap(decode(Schema.String, "deployment URL")));
+const makeFunctionApi = (url, key) => ({ call: (path, args, componentPath) => post(`${url}/api/${componentPath === void 0 ? "query" : "function"}`, { Authorization: `Convex ${Redacted.value(key)}` }, {
+	...componentPath === void 0 ? {} : { componentPath },
+	path,
+	args,
+	format: "json"
+}).pipe(Effect.flatMap(decode(Reply, `reply of ${path}`)), Effect.flatMap((reply) => reply.status === "success" ? Effect.succeed(reply.value) : Effect.fail(failure(reply.errorMessage.trim())))) });
+/** The state of the alchemyState mount: "active", "unmounted" (its rows are kept), or undefined. */
+const mountOf = (api) => api.call("_system/frontend/components:list", {}).pipe(Effect.flatMap(decode(Components, "component list")), Effect.map((components) => components.find((c) => c.path === COMPONENT_PATH)?.state));
+/** The component functions with Alchemy's encoding: the JSON text of encodeState. */
+const remoteOf = (api) => {
+	const run = (name, args) => api.call(`state:${name}`, args, COMPONENT_PATH);
+	const strings = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.Array(Schema.String), name)));
+	const optional = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.NullOr(Schema.String), name)));
+	const encode = (value) => JSON.stringify(encodeState(value));
+	return {
+		listStacks: () => strings("stacks", {}),
+		listStages: (stack) => strings("stages", { stack }),
+		list: (r) => strings("list", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		get: (r) => optional("get", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		getReplacedResources: (r) => strings("replaced", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((texts) => texts.map((text) => JSON.parse(text, reviveState)))),
+		getOutput: (r) => optional("getOutput", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		set: (r) => run("set", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn,
+			value: encode(r.value)
+		}),
+		delete: (r) => run("remove", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}),
+		deleteStack: (r) => run("removeStack", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		setOutput: (r) => run("setOutput", {
+			stack: r.stack,
+			stage: r.stage,
+			value: encode(r.value)
+		})
+	};
+};
+const unmounted = failure(`the ${COMPONENT_PATH} component of the deployment is unmounted. Its rows are kept: mount @samebase/alchemy-convex/convex.config in convex/convex.config.ts again.`);
+/**
+* The StateService over `api`. Without an alchemyState component at
+* the start, the state of the run stays in memory until a write finds the
+* component active.
+*/
+const makeConvexState = (api) => Effect.gen(function* () {
+	const remote = remoteOf(api);
+	const mount = yield* mountOf(api);
+	if (mount === "unmounted") return yield* unmounted;
+	let pending = mount === void 0;
+	const rows = {};
+	const outputs = {};
+	const memory = yield* InMemoryService(rows, outputs);
+	/** Moves the memory to the component once it is active. Rows that the run did not read stop it. */
+	const flush = Effect.gen(function* () {
+		const now = yield* mountOf(api);
+		if (now === void 0) return;
+		if (now !== "active") return yield* unmounted;
+		const stages = [.../* @__PURE__ */ new Set([...Object.keys(rows), ...Object.keys(outputs)])].flatMap((stack) => [.../* @__PURE__ */ new Set([...Object.keys(rows[stack] ?? {}), ...Object.keys(outputs[stack] ?? {})])].map((stage) => ({
+			stack,
+			stage
+		})));
+		for (const { stack, stage } of stages) {
+			const found = yield* remote.list({
+				stack,
+				stage
+			});
+			if (found.length > 0) return yield* failure(`${stack}/${stage} has ${found.length} rows in the deployment that this run did not read, so the run wrote none. Run it again.`);
+		}
+		for (const { stack, stage } of stages) {
+			for (const [fqn, value] of Object.entries(rows[stack]?.[stage] ?? {})) yield* remote.set({
+				stack,
+				stage,
+				fqn,
+				value
+			});
+			const byStage = outputs[stack];
+			if (byStage !== void 0 && stage in byStage) yield* remote.setOutput({
+				stack,
+				stage,
+				value: byStage[stage]
+			});
+		}
+		pending = false;
+	});
+	const read = (inMemory, inConvex) => Effect.suspend(() => pending ? inMemory : inConvex);
+	const write = (inMemory, inConvex, result) => Effect.suspend(() => pending ? Effect.tap(inMemory, () => flush) : Effect.as(inConvex, result));
+	return {
+		id: "convex",
+		getVersion: () => Effect.succeed(STATE_STORE_VERSION),
+		listStacks: () => read(memory.listStacks(), remote.listStacks()),
+		listStages: (stack) => read(memory.listStages(stack), remote.listStages(stack)),
+		list: (request) => read(memory.list(request), remote.list(request)),
+		get: (request) => read(memory.get(request), remote.get(request)),
+		getReplacedResources: (request) => read(memory.getReplacedResources(request), remote.getReplacedResources(request)),
+		getOutput: (request) => read(memory.getOutput(request), remote.getOutput(request)),
+		set: (request) => write(memory.set(request), remote.set(request), request.value),
+		delete: (request) => write(memory.delete(request), remote.delete(request), void 0),
+		deleteStack: (request) => write(memory.deleteStack(request), remote.deleteStack(request), void 0),
+		setOutput: (request) => write(memory.setOutput(request), remote.setOutput(request), request.value).pipe(Effect.tap(() => pending ? Effect.fail(failure(`the deployment of ${STATE_DEPLOY_KEY_ENV} has no ${COMPONENT_PATH} component at the end of the run, so this run saved no state. Mount @samebase/alchemy-convex/convex.config in convex/convex.config.ts.`)) : Effect.void))
+	};
+});
+/**
+* Alchemy state in the alchemyState component of the deployment that the
+* deploy key in CONVEX_STATE_DEPLOY_KEY names: the production deployment of
+* the project. The key needs the actions `deployment:data:view` and
+* `deployment:data:write`.
+*/
+const state = () => Layer.effect(State, Effect.gen(function* () {
+	const context = yield* Effect.context();
+	return yield* Effect.cached(Effect.gen(function* () {
+		const key = yield* Config.Redacted(STATE_DEPLOY_KEY_ENV);
+		if (keyTargetOf(Redacted.value(key)).kind !== "deployment") return yield* failure(`${STATE_DEPLOY_KEY_ENV} must be the deploy key of one deployment, such as prod:<name>|..., not a preview deploy key.`);
+		return yield* makeConvexState(makeFunctionApi(yield* urlForKey(key), key));
+	}).pipe(Effect.provideContext(context), Effect.orDie));
+}));
+//#endregion
+export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, STATE_DEPLOY_KEY_ENV, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers, state };
 
 //# sourceMappingURL=index.js.map