alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/lib/Railway/Redis.d.ts

@@ -0,0 +1,220 @@
+import * as railway from "@distilled.cloud/railway";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { type Project } from "./Project.ts";
+import type { Providers } from "./Providers.ts";
+/**
+ * A resource-valued prop: the resource itself, or an Effect that produces
+ * it (so `yield* Project(...)` and `Project(...)` both type-check).
+ */
+type Ref<T> = T | Effect.Effect<T, never, Providers>;
+/**
+ * Environment identity a Redis service is deployed into. Accepts a
+ * `Railway.Project` (its primary environment), a `Railway.Environment`,
+ * or an `{ environmentId }` stub.
+ */
+export type RedisEnvironment = {
+    readonly environmentId: string;
+};
+export declare const DEFAULT_REDIS_IMAGE = "redis:7";
+export declare const REDIS_PORT = 6379;
+import { REDIS_URL_ENV } from "./RedisBinding.ts";
+export { REDIS_URL_ENV };
+export declare const REDIS_PASSWORD_ENV = "REDISPASSWORD";
+export interface RedisProps {
+    /**
+     * Parent Railway Project. Accepts a `Railway.Project` or an Effect
+     * that produces one. Changing the Project replaces Redis.
+     */
+    project: Ref<Project>;
+    /**
+     * Environment to deploy into. Accepts a `Railway.Project` (primary
+     * environment), a `Railway.Environment`, or `{ environmentId }`.
+     * Defaults to the project's primary environment. Changing it replaces
+     * Redis.
+     */
+    environment?: Ref<RedisEnvironment>;
+    /**
+     * Service name. Unique per Project. If omitted, a unique name is
+     * generated from the stack, stage and logical ID. Changing it updates
+     * in place via `serviceUpdate`.
+     */
+    name?: string;
+    /**
+     * Docker image. Official Redis (`redis:7`) gets `--requirepass`.
+     * Bitnami (`bitnami/redis`) reads `REDIS_PASSWORD`.
+     *
+     * @default "redis:7"
+     */
+    image?: string;
+    /**
+     * Region for the service instance (`us-west2`, `us-east4`, …). If
+     * omitted, Railway picks the default. Updates in place.
+     */
+    region?: string;
+    /**
+     * Redis password. Wrap with `Redacted.make(...)`. If omitted, a
+     * password is generated on first create and kept. Never persisted in
+     * attributes.
+     */
+    password?: Redacted.Redacted<string> | string;
+}
+export type Redis = Resource<"Railway.Redis", RedisProps, {
+    /** Railway service id. */
+    serviceId: string;
+    /** Physical service name (unique per project). */
+    name: string;
+    /** Parent Railway project id. */
+    projectId: string;
+    /** Environment the instance is deployed in. */
+    environmentId: string;
+    /** Observed `source.image`. */
+    image: string;
+    /** Observed region, if Railway reported one. */
+    region: string | undefined;
+    /** Redis listen port (`6379`). */
+    port: number;
+    /** Private hostname (`{name}.railway.internal`). */
+    privateHost: string;
+    /** Latest deployment id, if one exists. */
+    deploymentId: string | undefined;
+    /** Latest deployment status (`SUCCESS`, `DEPLOYING`, …). */
+    deploymentStatus: string | undefined;
+}, never, Providers>;
+declare const RedisResource: import("../Resource.ts").ResourceClass<Redis>;
+/**
+ * A Railway.Redis is a Redis container in a Project (`redis:7` or
+ * `bitnami/redis`). Alchemy writes `REDIS_URL` / `REDISPASSWORD` on the
+ * service. Bind {@link ReadRedis}, {@link WriteRedis}, or
+ * {@link ReadWriteRedis} on a {@link Service}. Reach it from a laptop
+ * through {@link TcpProxy} on port `6379`.
+ *
+ * @see https://docs.railway.com/guides/redis
+ *
+ * ### Create Redis
+ * Pass a Project. Alchemy generates a unique name and password unless
+ * you pass them. Default image is `redis:7`.
+ *
+ * **Example:** Generated name
+ * ```typescript
+ * const site = yield* Railway.Project("Site");
+ * const cache = yield* Railway.Redis("Cache", { project: site });
+ * ```
+ *
+ * :::note
+ * Prefer omitting `name` in tests and CI so names stay unique and
+ * reclaimable.
+ * :::
+ *
+ * ### A stable name
+ * Pass `name` when you want a stable service name. Changing it later
+ * updates the service in place.
+ *
+ * **Example:** Explicit name
+ * ```typescript
+ * const cache = yield* Railway.Redis("Cache", {
+ *   project: site,
+ *   name: "cache",
+ * });
+ * ```
+ *
+ * ### Image
+ * Official Redis (`redis:7`) is started with `--requirepass`. Bitnami
+ * reads `REDIS_PASSWORD`. Updating the image is in place.
+ *
+ * **Example:** Bitnami
+ * ```typescript
+ * const cache = yield* Railway.Redis("Cache", {
+ *   project: site,
+ *   image: "bitnami/redis",
+ * });
+ * ```
+ *
+ * ### Public TCP
+ * Attach a {@link TcpProxy} on `6379` to reach Redis from outside the
+ * private network.
+ *
+ * **Example:** Laptop access
+ * ```typescript
+ * const cache = yield* Railway.Redis("Cache", { project: site });
+ * const proxy = yield* Railway.TcpProxy("CacheProxy", {
+ *   redis: cache,
+ *   environment: site,
+ *   applicationPort: 6379,
+ * });
+ * ```
+ *
+ * ### Bind from a Service
+ * Yield {@link ReadWriteRedis} (or {@link ReadRedis} / {@link WriteRedis})
+ * in Service init. Provide the matching `*Http` layer. Runtime commands
+ * use `REDIS_URL` (`{name}.railway.internal`).
+ *
+ * **Example:** Read and write
+ * ```typescript
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * export const Site = Railway.Project("Site");
+ * export const Cache = Railway.Redis("Cache", { project: Site });
+ *
+ * export default class Api extends Railway.Service<Api>()(
+ *   "Api",
+ *   { project: Site, main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const cache = yield* Railway.ReadWriteRedis(Cache);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* cache.set("marker", "hello");
+ *         const value = yield* cache.get("marker");
+ *         return HttpServerResponse.json({ value });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Railway.ReadWriteRedisHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Module-scope declarations
+ * Resource-valued props accept the resource or an Effect producing it.
+ *
+ * **Example:** Module-scope Redis
+ * ```typescript
+ * // src/cache.ts
+ * import * as Railway from "alchemy/Railway";
+ *
+ * export const Site = Railway.Project("Site");
+ * export const Cache = Railway.Redis("Cache", { project: Site });
+ * ```
+ *
+ * @resource
+ */
+export declare const Redis: typeof RedisResource;
+export { CommandError as RedisCommandError, UrlMissing as RedisUrlMissing, } from "../Redis/index.ts";
+declare const RedisNotCreated_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Railway.RedisNotCreated";
+} & Readonly<A>;
+export declare class RedisNotCreated extends RedisNotCreated_base<{
+    name: string;
+    projectId: string;
+}> {
+}
+declare const RedisProjectRequired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Railway.RedisProjectRequired";
+} & Readonly<A>;
+export declare class RedisProjectRequired extends RedisProjectRequired_base<{
+    message: string;
+}> {
+}
+declare const RedisDeployFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Railway.RedisDeployFailed";
+} & Readonly<A>;
+export declare class RedisDeployFailed extends RedisDeployFailed_base<{
+    serviceId: string;
+    status: string;
+    deploymentId: string | undefined;
+}> {
+}
+export declare const isRedisImage: (image: string | null | undefined) => boolean;
+export { command as redisCommand, connectionUrl as redisConnectionUrl, run as runRedisCommand, } from "../Redis/index.ts";
+export declare const RedisProvider: () => import("effect/Layer").Layer<Provider.Provider<Redis>, never, import("./Environment.ts").RailwayEnvironment | import("../Stack.ts").Stack | import("../Stage.ts").Stage | railway.RailwayOpContext>;
+//# sourceMappingURL=Redis.d.ts.map

package/lib/Railway/Redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Redis.d.ts","sourceRoot":"","sources":["../../src/Railway/Redis.ts"],"names":[],"mappings":"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"}