sailfork / t3code-github / .repos/ alchemy-effect/ packages/ railway/ src/ ref.ts

/**
 * A Railway variable-reference template (`${{Service.KEY}}` or
 * `${{shared.NAME}}`). Pass as {@link Variable} `value` or `Service.env`.
 *
 * Distinct from the unexported resource-prop `Ref<T>`. Never export that
 * `Ref`.
 */
export type VariableRef = string;

/**
 * Something `Railway.ref` can take a namespace from: `"shared"`, an
 * explicit service name, or a resource's `LogicalId`.
 */
export type VariableRefSource =
  | string
  | {
      readonly LogicalId: string;
    };

const SHARED = "shared";

const namespaceOf = (resource: VariableRefSource): string => {
  if (typeof resource === "string") {
    const trimmed = resource.trim();
    return trimmed.length > 0 ? trimmed : SHARED;
  }
  const logical = typeof resource.LogicalId === "string" ? resource.LogicalId.trim() : "";
  return logical.length > 0 ? logical : SHARED;
};

/**
 * Emit a Railway variable-reference template (`${{Service.KEY}}` or
 * `${{shared.NAME}}`). Distinct from the unexported resource-prop
 * `Ref<T>` — never export that `Ref`.
 *
 * `Railway.ref(Db, "DATABASE_URL")` returns `${{LogicalName.DATABASE_URL}}`
 * where `LogicalName` is `resource.LogicalId` (`Postgres("Db")` → `Db`).
 * Shared variables use the `"shared"` namespace:
 * `Railway.ref("shared", "SENTRY_DSN")` returns `${{shared.SENTRY_DSN}}`.
 *
 * Store the string as a {@link Variable} `value` (or on `Service.env`).
 * Railway keeps the template (`unrendered: true`) and interpolates it at
 * build/runtime — it is not a resolved URI. Use {@link ConnectPostgres}
 * when you want a typed client inside an Effect-native Service.
 *
 * Railway interpolates by service name. Set `name` on Postgres/Service to
 * the LogicalId if you need the template to resolve to that service.
 *
 * @see https://docs.railway.com/variables/reference#template-syntax
 * @see https://docs.railway.com/infrastructure-as-code/reference
 *
 * ### Reference a service variable
 * Pass a resource (or its LogicalId) and the variable key. The result is
 * a template string, not a URI.
 *
 * **Example:** Reference Postgres DATABASE_URL
 * ```typescript
 * const db = yield* Railway.Postgres("Db", { project: site });
 * yield* Railway.Variable("DatabaseUrl", {
 *   project: site,
 *   service: api,
 *   name: "DATABASE_URL",
 *   value: Railway.ref(db, "DATABASE_URL"),
 * });
 * ```
 *
 * ### Shared variables
 * `"shared"` is the environment-wide namespace (IaC `ctx.shared.NAME`).
 *
 * **Example:** Shared variable
 * ```typescript
 * env: {
 *   SENTRY_DSN: Railway.ref("shared", "SENTRY_DSN"),
 * }
 * ```
 *
 * @resource
 * @product Project
 */
export const ref = (resource: VariableRefSource, key: string): VariableRef =>
  `\${{${namespaceOf(resource)}.${key}}}`;