The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { BundleConfig } from "alchemy/Bundle/Bundle"; |
| 2 | import type { Input } from "alchemy/Input"; |
| 3 | import { Platform, type Main, type PlatformProps } from "alchemy/Platform"; |
| 4 | import type { Resource } from "alchemy/Resource"; |
| 5 | import * as Effect from "effect/Effect"; |
| 6 | import type * as Redacted from "effect/Redacted"; |
| 7 | import type { BranchScope } from "./BranchScope.ts"; |
| 8 | import type { FunctionEnvironment, FunctionRequest } from "./FunctionEnvironment.ts"; |
| 9 | import { |
| 10 | makeFunctionRuntimeContext, |
| 11 | type FunctionRuntimeContext, |
| 12 | } from "./FunctionRuntimeContext.ts"; |
| 13 | import type { Providers } from "./Providers.ts"; |
| 14 | |
| 15 | /** |
| 16 | * Prebuilt Node 24 Fetch application. The directory or ZIP must contain |
| 17 | * `index.mjs` at its root, exporting a Fetch handler or an object with `fetch`. |
| 18 | * Include all runtime dependencies; Alchemy does not bundle prebuilt artifacts. |
| 19 | * Archives must not contain symlinks, traversal paths, or deployment secrets. |
| 20 | */ |
| 21 | export type FunctionArtifact = |
| 22 | | { |
| 23 | /** Directory packaged into a deterministic ZIP. */ directory: string; |
| 24 | zip?: never; |
| 25 | } |
| 26 | | { /** Path to an existing ZIP archive. */ zip: string; directory?: never }; |
| 27 | |
| 28 | /** |
| 29 | * {@link BranchScope} where the branch or project may also be an Effect that |
| 30 | * produces it, so `{ branch: Main }` and `{ branch: yield* Main }` both |
| 31 | * type-check. |
| 32 | */ |
| 33 | export type FunctionBranchScope = |
| 34 | | { |
| 35 | /** Branch resource or explicit branch identity, or an Effect producing one. */ |
| 36 | branch: |
| 37 | | { projectId: string; branchId: string } |
| 38 | | Effect.Effect<Input<{ projectId: string; branchId: string }>, never, any>; |
| 39 | project?: never; |
| 40 | } |
| 41 | | { |
| 42 | /** Project whose default branch is selected at reconciliation time, or an Effect producing one. */ |
| 43 | project: { projectId: string } | Effect.Effect<Input<{ projectId: string }>, never, any>; |
| 44 | branch?: never; |
| 45 | }; |
| 46 | |
| 47 | /** |
| 48 | * The scope as providers see it. `transformProps` yields an Effect-valued |
| 49 | * `branch` or `project` before any lifecycle operation runs, so only the |
| 50 | * resolved shape reaches the provider. |
| 51 | */ |
| 52 | export const branchScopeOf = <P extends FunctionBranchScope>(props: P) => props as P & BranchScope; |
| 53 | |
| 54 | export interface FunctionCommonProps extends PlatformProps { |
| 55 | /** Immutable lowercase alphanumeric identifier, at most 20 characters. Generated when omitted. */ |
| 56 | slug?: string; |
| 57 | /** Mutable display name. Removing it restores the slug. */ |
| 58 | name?: string; |
| 59 | /** Write-only values. Removing a managed key sends an empty deletion value. Platform-injected keys cannot be overridden. */ |
| 60 | env?: Record<string, string | Redacted.Redacted<string> | undefined>; |
| 61 | /** Node-targeted bundler options; not used with prebuilt artifacts. */ |
| 62 | bundle?: BundleConfig; |
| 63 | /** Local Neon CLI executable (version 2.45.0 or newer) and optional listening port. */ |
| 64 | dev?: { command?: string; port?: number }; |
| 65 | } |
| 66 | |
| 67 | export type FunctionProps = FunctionBranchScope & |
| 68 | FunctionCommonProps & |
| 69 | ( |
| 70 | | { |
| 71 | /** Native Fetch or Effect entry module. */ main: string; |
| 72 | artifact?: never; |
| 73 | } |
| 74 | | { |
| 75 | /** Prebuilt Fetch application, mutually exclusive with main. */ artifact: FunctionArtifact; |
| 76 | main?: never; |
| 77 | } |
| 78 | ); |
| 79 | |
| 80 | export interface FunctionAttributes { |
| 81 | /** Owning project. */ projectId: string; |
| 82 | /** Owning branch. */ branchId: string; |
| 83 | /** Stable function ID. */ functionId: string; |
| 84 | /** Immutable invocation slug. */ slug: string; |
| 85 | /** Observed display name. */ name: string; |
| 86 | /** Public invocation URL. Authenticate callers in the handler. */ url: string; |
| 87 | /** Latest deployment identifier. */ currentDeploymentId: number | undefined; |
| 88 | /** Deployment currently serving traffic. */ activeDeploymentId: number | undefined; |
| 89 | /** Latest deployment build status. */ status: string | undefined; |
| 90 | /** Digest of the last successfully applied artifact, not a remote code attestation. */ codeHash: |
| 91 | | string |
| 92 | | undefined; |
| 93 | /** Last applied environment digest, not proof of remote write-only value equality. */ environmentHash?: string; |
| 94 | /** Previously managed environment names. Values cannot be read back. */ environment: string[]; |
| 95 | } |
| 96 | |
| 97 | export interface FunctionBinding { |
| 98 | /** Namespaced application configuration; conflicts with user values are rejected. */ |
| 99 | env?: Record<string, string | Redacted.Redacted<string> | undefined>; |
| 100 | } |
| 101 | |
| 102 | export interface Function extends Resource< |
| 103 | "Neon.Function", |
| 104 | FunctionProps, |
| 105 | FunctionAttributes, |
| 106 | FunctionBinding, |
| 107 | Providers |
| 108 | > {} |
| 109 | |
| 110 | /** |
| 111 | * Node.js 24 Fetch function, with native and Effect entrypoints. |
| 112 | * |
| 113 | * Functions have public URLs. The `functions:invoke` credential scope does not |
| 114 | * establish a private invocation policy. Authenticate requests in your handler. |
| 115 | * Native same-branch database/storage credentials are injected by Neon; a typed |
| 116 | * read-only binding does not restrict the credentials available to the process. |
| 117 | * Explicit adoption takes ownership of user-defined environment names: existing |
| 118 | * keys omitted from `env` and bindings are removed. Values are write-only, so |
| 119 | * cached digests cannot detect out-of-band value drift. |
| 120 | * |
| 121 | * ### Streaming disconnects <!-- api-prose --> |
| 122 | * |
| 123 | * Neon’s production host currently does not reliably propagate client disconnects |
| 124 | * to uncompressed response streams. An abandoned stream can retain its producer |
| 125 | * and request-scoped resources until it finishes. Prefer finite responses and |
| 126 | * application-bounded streams; do not rely on disconnect cleanup for long-lived |
| 127 | * streaming workloads until [the upstream issue](https://github.com/neondatabase/neon-pkgs/issues/636) |
| 128 | * is resolved. Alchemy propagates abort and body-cancel signals when the host supplies them. |
| 129 | * |
| 130 | * ### Native Fetch |
| 131 | * **Example:** Bundle a native object, bare handler, or Hono application |
| 132 | * ```typescript |
| 133 | * const api = yield* Neon.Function("Api", { branch, main: "./src/api.ts" }); |
| 134 | * ``` |
| 135 | * |
| 136 | * ### Effect Fetch |
| 137 | * **Example:** Class entrypoint |
| 138 | * ```typescript |
| 139 | * export default class Api extends Neon.Function<Api>()( |
| 140 | * "Api", { branch, main: import.meta.url }, |
| 141 | * Effect.succeed({ fetch: Effect.succeed(HttpServerResponse.text("ok")) }), |
| 142 | * ) {} |
| 143 | * ``` |
| 144 | * |
| 145 | * ### Prebuilt Applications |
| 146 | * **Example:** Deploy Website build output without rebundling |
| 147 | * ```typescript |
| 148 | * const site = yield* Neon.Function("Site", { branch, artifact: { directory: "./dist" } }); |
| 149 | * ``` |
| 150 | * |
| 151 | * @resource |
| 152 | * @product Function |
| 153 | */ |
| 154 | export const Function: Platform< |
| 155 | Function, |
| 156 | FunctionEnvironment, |
| 157 | Main<FunctionEnvironment | FunctionRequest>, |
| 158 | FunctionRuntimeContext |
| 159 | > = Platform<Function>("Neon.Function", { |
| 160 | createRuntimeContext: makeFunctionRuntimeContext, |
| 161 | // `{ branch: Main }` at module scope is an Effect. Yield it here so the |
| 162 | // branch (or project) is registered and resolved at reconcile (same as |
| 163 | // `yield* Main` inside Effect.gen). |
| 164 | transformProps: (_id, props) => |
| 165 | Effect.gen(function* () { |
| 166 | if (globalThis.__ALCHEMY_RUNTIME__) return props; |
| 167 | const yieldRef = (value: unknown) => |
| 168 | // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props refs are declaration Effects resolved by the engine |
| 169 | Effect.isEffect(value) ? (value as Effect.Effect<unknown>) : Effect.succeed(value); |
| 170 | return { |
| 171 | ...props, |
| 172 | ...(props.branch !== undefined ? { branch: yield* yieldRef(props.branch) } : {}), |
| 173 | ...(props.project !== undefined ? { project: yield* yieldRef(props.project) } : {}), |
| 174 | }; |
| 175 | }), |
| 176 | }); |