sailfork / t3code-github / .repos/ alchemy-effect/ packages/ neon/ src/ Function.ts

import type { BundleConfig } from "alchemy/Bundle/Bundle";
import type { Input } from "alchemy/Input";
import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
import type { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import type { BranchScope } from "./BranchScope.ts";
import type { FunctionEnvironment, FunctionRequest } from "./FunctionEnvironment.ts";
import {
  makeFunctionRuntimeContext,
  type FunctionRuntimeContext,
} from "./FunctionRuntimeContext.ts";
import type { Providers } from "./Providers.ts";

/**
 * Prebuilt Node 24 Fetch application. The directory or ZIP must contain
 * `index.mjs` at its root, exporting a Fetch handler or an object with `fetch`.
 * Include all runtime dependencies; Alchemy does not bundle prebuilt artifacts.
 * Archives must not contain symlinks, traversal paths, or deployment secrets.
 */
export type FunctionArtifact =
  | {
      /** Directory packaged into a deterministic ZIP. */ directory: string;
      zip?: never;
    }
  | { /** Path to an existing ZIP archive. */ zip: string; directory?: never };

/**
 * {@link BranchScope} where the branch or project may also be an Effect that
 * produces it, so `{ branch: Main }` and `{ branch: yield* Main }` both
 * type-check.
 */
export type FunctionBranchScope =
  | {
      /** Branch resource or explicit branch identity, or an Effect producing one. */
      branch:
        | { projectId: string; branchId: string }
        | Effect.Effect<Input<{ projectId: string; branchId: string }>, never, any>;
      project?: never;
    }
  | {
      /** Project whose default branch is selected at reconciliation time, or an Effect producing one. */
      project: { projectId: string } | Effect.Effect<Input<{ projectId: string }>, never, any>;
      branch?: never;
    };

/**
 * The scope as providers see it. `transformProps` yields an Effect-valued
 * `branch` or `project` before any lifecycle operation runs, so only the
 * resolved shape reaches the provider.
 */
export const branchScopeOf = <P extends FunctionBranchScope>(props: P) => props as P & BranchScope;

export interface FunctionCommonProps extends PlatformProps {
  /** Immutable lowercase alphanumeric identifier, at most 20 characters. Generated when omitted. */
  slug?: string;
  /** Mutable display name. Removing it restores the slug. */
  name?: string;
  /** Write-only values. Removing a managed key sends an empty deletion value. Platform-injected keys cannot be overridden. */
  env?: Record<string, string | Redacted.Redacted<string> | undefined>;
  /** Node-targeted bundler options; not used with prebuilt artifacts. */
  bundle?: BundleConfig;
  /** Local Neon CLI executable (version 2.45.0 or newer) and optional listening port. */
  dev?: { command?: string; port?: number };
}

export type FunctionProps = FunctionBranchScope &
  FunctionCommonProps &
  (
    | {
        /** Native Fetch or Effect entry module. */ main: string;
        artifact?: never;
      }
    | {
        /** Prebuilt Fetch application, mutually exclusive with main. */ artifact: FunctionArtifact;
        main?: never;
      }
  );

export interface FunctionAttributes {
  /** Owning project. */ projectId: string;
  /** Owning branch. */ branchId: string;
  /** Stable function ID. */ functionId: string;
  /** Immutable invocation slug. */ slug: string;
  /** Observed display name. */ name: string;
  /** Public invocation URL. Authenticate callers in the handler. */ url: string;
  /** Latest deployment identifier. */ currentDeploymentId: number | undefined;
  /** Deployment currently serving traffic. */ activeDeploymentId: number | undefined;
  /** Latest deployment build status. */ status: string | undefined;
  /** Digest of the last successfully applied artifact, not a remote code attestation. */ codeHash:
    | string
    | undefined;
  /** Last applied environment digest, not proof of remote write-only value equality. */ environmentHash?: string;
  /** Previously managed environment names. Values cannot be read back. */ environment: string[];
}

export interface FunctionBinding {
  /** Namespaced application configuration; conflicts with user values are rejected. */
  env?: Record<string, string | Redacted.Redacted<string> | undefined>;
}

export interface Function extends Resource<
  "Neon.Function",
  FunctionProps,
  FunctionAttributes,
  FunctionBinding,
  Providers
> {}

/**
 * Node.js 24 Fetch function, with native and Effect entrypoints.
 *
 * Functions have public URLs. The `functions:invoke` credential scope does not
 * establish a private invocation policy. Authenticate requests in your handler.
 * Native same-branch database/storage credentials are injected by Neon; a typed
 * read-only binding does not restrict the credentials available to the process.
 * Explicit adoption takes ownership of user-defined environment names: existing
 * keys omitted from `env` and bindings are removed. Values are write-only, so
 * cached digests cannot detect out-of-band value drift.
 *
 * ### Streaming disconnects <!-- api-prose -->
 *
 * Neon’s production host currently does not reliably propagate client disconnects
 * to uncompressed response streams. An abandoned stream can retain its producer
 * and request-scoped resources until it finishes. Prefer finite responses and
 * application-bounded streams; do not rely on disconnect cleanup for long-lived
 * streaming workloads until [the upstream issue](https://github.com/neondatabase/neon-pkgs/issues/636)
 * is resolved. Alchemy propagates abort and body-cancel signals when the host supplies them.
 *
 * ### Native Fetch
 * **Example:** Bundle a native object, bare handler, or Hono application
 * ```typescript
 * const api = yield* Neon.Function("Api", { branch, main: "./src/api.ts" });
 * ```
 *
 * ### Effect Fetch
 * **Example:** Class entrypoint
 * ```typescript
 * export default class Api extends Neon.Function<Api>()(
 *   "Api", { branch, main: import.meta.url },
 *   Effect.succeed({ fetch: Effect.succeed(HttpServerResponse.text("ok")) }),
 * ) {}
 * ```
 *
 * ### Prebuilt Applications
 * **Example:** Deploy Website build output without rebundling
 * ```typescript
 * const site = yield* Neon.Function("Site", { branch, artifact: { directory: "./dist" } });
 * ```
 *
 * @resource
 * @product Function
 */
export const Function: Platform<
  Function,
  FunctionEnvironment,
  Main<FunctionEnvironment | FunctionRequest>,
  FunctionRuntimeContext
> = Platform<Function>("Neon.Function", {
  createRuntimeContext: makeFunctionRuntimeContext,
  // `{ branch: Main }` at module scope is an Effect. Yield it here so the
  // branch (or project) is registered and resolved at reconcile (same as
  // `yield* Main` inside Effect.gen).
  transformProps: (_id, props) =>
    Effect.gen(function* () {
      if (globalThis.__ALCHEMY_RUNTIME__) return props;
      const yieldRef = (value: unknown) =>
        // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props refs are declaration Effects resolved by the engine
        Effect.isEffect(value) ? (value as Effect.Effect<unknown>) : Effect.succeed(value);
      return {
        ...props,
        ...(props.branch !== undefined ? { branch: yield* yieldRef(props.branch) } : {}),
        ...(props.project !== undefined ? { project: yield* yieldRef(props.project) } : {}),
      };
    }),
});