@sst-community/sst 4.20.0 → 5.0.0-alpha.1

package/platform/src/global-aliases.d.ts

@@ -0,0 +1,37 @@
+// The globals that are aliases of modules, `sst` and `$util`, which an app's
+// config.d.ts has with global.d.ts. They're on their own so that the
+// platform's declarations are built without them: then the declarations name
+// SST's and Pulumi's types through their modules, as `sst/components` does,
+// and a component package reads them without an app's config.d.ts. The docs
+// put them back in global.d.ts (www/generate.ts).
+import * as util from "@pulumi/pulumi";
+import * as _sst from "./components/index";
+
+declare global {
+  // @ts-expect-error
+  export import sst = _sst;
+
+  /**
+   * A convenience reference to the [`util`](https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/pulumi/) module from Pulumi.
+   *
+   * This is useful for working with components. You can use these without importing or installing the Pulumi SDK.
+   *
+   * @example
+   *
+   * For example, to create a new asset, you can:
+   *
+   * ```ts title="sst.config.ts"
+   * const myFiles = new $util.asset.FileArchive("./path/to/files");
+   * ```
+   *
+   * This is equivalent to doing:
+   *
+   * ```ts title="sst.config.ts"
+   * import * as pulumi from "@pulumi/pulumi";
+   *
+   * const myFiles = new pulumi.asset.FileArchive("./path/to/files");
+   * ```
+   */
+  // @ts-expect-error
+  export import $util = util;
+}

package/platform/src/global.d.ts

@@ -0,0 +1,374 @@
+/**
+ * The Global library is a collection of `$` functions and variables that are available in the `run` function, of your [`sst.config.ts`](/docs/reference/config/).
+ *
+ * You don't need to import the Global library. It's available in the `run` function of your `sst.config.ts`.
+ *
+ * :::note
+ * The Global library is only available in the `run` function of your `sst.config.ts`.
+ * :::
+ *
+ * For example, you can get the name of your app in your app config using `$app.name`.
+ *
+ * ```ts title="sst.config.ts" {4}
+ * export default $config({
+ *   // ...
+ *   async run() {
+ *     console.log($app.name);
+ *   }
+ * });
+ * ```
+ *
+ * The **variables** contain the context of the app that's being run. While the **functions** help you work with the [Outputs of components](/docs/components##inputs--outputs).
+ *
+ * @packageDocumentation
+ */
+
+import "@types/node";
+import * as util from "@pulumi/pulumi";
+import { $config as config, App } from "./config";
+
+type Simplify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/** @internal */
+interface $APP
+  extends Readonly<{
+    /**
+     * The name of the current app.
+     */
+    name: string;
+    /**
+     * The stage currently being run. You can use this to conditionally deploy resources based
+     * on the stage.
+     *
+     * For example, to deploy a bucket only in the `dev` stage:
+     *
+     * ```ts title="sst.config.ts"
+     * if ($app.stage === "dev") {
+     *   new sst.aws.Bucket("MyBucket");
+     * }
+     * ```
+     */
+    stage: string;
+    /**
+     * The removal policy for the current stage. If `removal` was not set in the `sst.config.ts`, this will be return its default value, `retain`.
+     */
+    removal: "remove" | "retain" | "retain-all";
+    /**
+     * The providers currently being used in the app.
+     */
+    providers: App["providers"];
+
+    /**
+     * If true, prevents `sst remove` from being executed on this stage
+     */
+    protect: boolean;
+  }> {}
+
+declare global {
+  /** @internal */
+  export const $linkable: typeof import("./components/link").Link.linkable;
+
+  /** @internal */
+  export const $output: typeof util.output;
+  /**
+   * Wait for a list of Output values to be resolved, and then apply a function to their resolved values.
+   *
+   * @example
+   * Say you had a couple of S3 Buckets:
+   * ```ts title="sst.config.ts"
+   * const bucket1 = new sst.aws.Bucket("MyBucket1");
+   * const bucket2 = new sst.aws.Bucket("MyBucket2");
+   * ```
+   *
+   * You can run a function after both of them are resolved:
+   *
+   * ```ts title="sst.config.ts"
+   * $resolve([bucket1.name, bucket2.name]).apply(([value1, value2]) =>
+   *   console.log({ value1, value2 })
+   * );
+   * ```
+   */
+  export function $resolve<T extends Record<string, any>>(
+    val: T,
+  ): util.Output<util.Unwrap<T>>;
+  export function $resolve<T1, T2, T3, T4, T5, T6, T7, T8>(
+    values: [
+      util.Input<T1>,
+      util.Input<T2>,
+      util.Input<T3>,
+      util.Input<T4>,
+      util.Input<T5>,
+      util.Input<T6>,
+      util.Input<T7>,
+      util.Input<T8>,
+    ],
+  ): util.Output<
+    [
+      util.Unwrap<T1>,
+      util.Unwrap<T2>,
+      util.Unwrap<T3>,
+      util.Unwrap<T4>,
+      util.Unwrap<T5>,
+      util.Unwrap<T6>,
+      util.Unwrap<T7>,
+      util.Unwrap<T8>,
+    ]
+  >;
+  export function $resolve<T1, T2, T3, T4, T5, T6, T7>(
+    values: [
+      util.Input<T1>,
+      util.Input<T2>,
+      util.Input<T3>,
+      util.Input<T4>,
+      util.Input<T5>,
+      util.Input<T6>,
+      util.Input<T7>,
+    ],
+  ): util.Output<
+    [
+      util.Unwrap<T1>,
+      util.Unwrap<T2>,
+      util.Unwrap<T3>,
+      util.Unwrap<T4>,
+      util.Unwrap<T5>,
+      util.Unwrap<T6>,
+      util.Unwrap<T7>,
+    ]
+  >;
+  export function $resolve<T1, T2, T3, T4, T5, T6>(
+    values: [
+      util.Input<T1>,
+      util.Input<T2>,
+      util.Input<T3>,
+      util.Input<T4>,
+      util.Input<T5>,
+      util.Input<T6>,
+    ],
+  ): util.Output<
+    [
+      util.Unwrap<T1>,
+      util.Unwrap<T2>,
+      util.Unwrap<T3>,
+      util.Unwrap<T4>,
+      util.Unwrap<T5>,
+      util.Unwrap<T6>,
+    ]
+  >;
+  export function $resolve<T1, T2, T3, T4, T5>(
+    values: [
+      util.Input<T1>,
+      util.Input<T2>,
+      util.Input<T3>,
+      util.Input<T4>,
+      util.Input<T5>,
+    ],
+  ): util.Output<
+    [
+      util.Unwrap<T1>,
+      util.Unwrap<T2>,
+      util.Unwrap<T3>,
+      util.Unwrap<T4>,
+      util.Unwrap<T5>,
+    ]
+  >;
+  export function $resolve<T1, T2, T3, T4>(
+    values: [util.Input<T1>, util.Input<T2>, util.Input<T3>, util.Input<T4>],
+  ): util.Output<[Unwrap<T1>, util.Unwrap<T2>, Unwrap<T3>, Unwrap<T4>]>;
+  export function $resolve<T1, T2, T3>(
+    values: [util.Input<T1>, util.Input<T2>, util.Input<T3>],
+  ): util.Output<[util.Unwrap<T1>, util.Unwrap<T2>, util.Unwrap<T3>]>;
+  export function $resolve<T1, T2>(
+    values: [util.Input<T1>, util.Input<T2>],
+  ): util.Output<[Unwrap<T1>, util.Unwrap<T2>]>;
+  /**
+   * Use string interpolation on Output values.
+   *
+   * @example
+   * This is takes care of resolving the Output values for you. Say you had a bucket:
+   *
+   * ```ts title="sst.config.ts"
+   * const bucket = new sst.aws.Bucket("MyBucket");
+   * ```
+   *
+   * Instead of resolving the bucket name first:
+   *
+   * ```ts title="sst.config.ts"
+   * const description = bucket.name.apply(name => `This is a bucket named ${name}`);
+   * ```
+   *
+   * You can directly do this:
+   * ```ts title="sst.config.ts"
+   * const description = $interpolate`This is a bucket named ${bucket.name}`;
+   * ```
+   */
+  export const $interpolate: typeof util.interpolate;
+  /**
+   * Takes a sequence of Output values or plain JavaScript values, stringifies each,
+   * and concatenates them into one final string.
+   *
+   * @example
+   * This is takes care of resolving the Output values for you. Say you had a bucket:
+   *
+   * ```ts title="sst.config.ts"
+   * const bucket = new sst.aws.Bucket("MyBucket");
+   * ```
+   *
+   * Instead of having to resolve the bucket name first::
+   *
+   * ```ts title="sst.config.ts"
+   * const description = bucket.name.apply(name =>
+   *   "This is a bucket named ".concat(name)
+   * );
+   * ```
+   *
+   * You can directly do this:
+   *
+   * ```ts title="sst.config.ts"
+   * const description = $concat("This is a bucket named ", bucket.name);
+   * ```
+   */
+  export const $concat: typeof util.concat;
+  /**
+   * Takes an Output value or plain JavaScript value, uses `JSON.parse`
+   * on the resolved JSON string to turn it into a JSON object.
+   *
+   * @example
+   * So for example, instead of doing of resolving the value first:
+   *
+   * ```ts title="sst.config.ts"
+   * const policy = policyStr.apply((policy) =>
+   *   JSON.parse(policy)
+   * );
+   * ```
+   *
+   * You can directly do this:
+   *
+   * ```ts title="sst.config.ts"
+   * const policy = $jsonParse(policyStr);
+   * ```
+   */
+  export const $jsonParse: typeof util.jsonParse;
+  /**
+   * Takes an Output value or plain JSON object, uses `JSON.stringify`
+   * on the resolved JSON object to turn it into a JSON string.
+   *
+   * @example
+   * So for example, instead of doing of resolving the value first:
+   *
+   * ```ts title="sst.config.ts"
+   * const policy = policyObj.apply((policy) =>
+   *   JSON.stringify(policy)
+   * );
+   * ```
+   *
+   * You can directly do this:
+   *
+   * ```ts title="sst.config.ts"
+   * const policy = $jsonStringify(policyObj);
+   * ```
+   */
+  export const $jsonStringify: typeof util.jsonStringify;
+
+  /**
+   * Context about the app being run.
+   */
+  export const $app: Simplify<$APP>;
+
+  /**
+   * Register a function that'll be called when a component of the given type is about
+   * to be created. This is useful for setting global defaults for your components.
+   *
+   * :::note
+   * This function is only called for components that are created **after** the function is registered.
+   * :::
+   *
+   * The function takes the arguments and options that are being passed to the component,
+   * and can modify them.
+   *
+   * @example
+   *
+   * For example, to set a default runtime for all function components.
+   *
+   * ```ts title="sst.config.ts"
+   * $transform(sst.aws.Function, (args, opts, name) => {
+   *   // Set the default if it's not set by the component
+   *   args.runtime ??= "nodejs24.x";
+   * });
+   * ```
+   *
+   * Here, `args`, `opts` and `name` are what you'd pass to the `Function` component. Recall
+   * the signature of the `Function` component:
+   *
+   * ```ts title="sst.config.ts"
+   * new sst.aws.Function(name: string, args: FunctionArgs, opts?: pulumi.ComponentResourceOptions)
+   * ```
+   */
+  export const $transform: typeof import("./components/component").$transform;
+
+  /**
+   * Packages a file or directory into a Pulumi asset. This can be used for Pulumi resources that
+   * take an asset as input.
+   *
+   * When the given path is a file, it returns a
+   * [`FileAsset`](https://www.pulumi.com/docs/iac/concepts/assets-archives/#assets). If the
+   * path is a directory, it returns a
+   * [`FileArchive`](https://www.pulumi.com/docs/iac/concepts/assets-archives/#assets) with the
+   * zipped contents of the directory.
+   *
+   * :::tip
+   * This automatically resolves paths relative to the root of the app.
+   * :::
+   *
+   * Relative paths are resolved relative to the root of the app. While, absolute paths are used as is.
+   *
+   * @example
+   *
+   * If you have a file inside the `images` directory at the root of your app, you can upload it
+   * to S3 on deploy.
+   *
+   * ```ts title="sst.config.ts" {7}
+   * const bucket = new aws.s3.Bucket("MyBucket");
+   *
+   * new aws.s3.BucketObjectv2("MyImage", {
+   *   bucket: bucket.name,
+   *   key: "public/spongebob.svg",
+   *   contentType: "image/svg+xml",
+   *   source: $asset("images/spongebob.svg"),
+   * });
+   * ```
+   *
+   * You can also use this to zip up the files in the `files/` directory and upload it to S3.
+   *
+   * ```ts title="sst.config.ts" {5}
+   * new aws.s3.BucketObjectv2("MyZip", {
+   *   bucket: bucket.name,
+   *   key: "public/spongebob.zip",
+   *   contentType: "application/zip",
+   *   source: $asset("files"),
+   * });
+   * ```
+   */
+  export const $asset: typeof import("./components/component").$asset;
+
+  /**
+   * Returns `true` if the app is running in `sst dev`.
+   */
+  export const $dev: boolean;
+
+  /** @internal */
+  export const $cli: {
+    command: string;
+    rpc: string;
+    paths: {
+      home: string;
+      root: string;
+      work: string;
+      platform: string;
+    };
+    state: {
+      version: Record<string, number>;
+    };
+  };
+}

package/platform/src/internal.d.ts

@@ -0,0 +1,18 @@
+declare global {
+  export const $cli: {
+    command: string;
+    rpc: string;
+    paths: {
+      home: string;
+      root: string;
+      work: string;
+      platform: string;
+    };
+    home: string;
+    state: {
+      version: Record<string, number>;
+    };
+  };
+}
+
+export const {};

package/platform/src/runtime/worker/unenv.d.ts

@@ -0,0 +1,14 @@
+export interface CloudflareUnenvInput {
+  date?: string;
+  flags?: string[];
+}
+
+export interface CloudflareUnenvConfig {
+  alias: Record<string, string>;
+  external: string[];
+  polyfill: string[];
+}
+
+export function getCloudflareUnenvConfig(
+  input?: CloudflareUnenvInput,
+): CloudflareUnenvConfig;

package/platform/src/runtime/worker/unenv.mjs

@@ -0,0 +1,26 @@
+import { getCloudflarePreset } from "@cloudflare/unenv-preset";
+import { defineEnv } from "unenv";
+import { fileURLToPath } from "node:url";
+
+export function getCloudflareUnenvConfig(input = {}) {
+  const { env } = defineEnv({
+    npmShims: true,
+    presets: [
+      getCloudflarePreset({
+        compatibilityDate: input.date,
+        compatibilityFlags: input.flags,
+      }),
+    ],
+  });
+
+  return {
+    alias: env.alias,
+    external: env.external,
+    polyfill: env.polyfill,
+  };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const input = process.argv[2] ? JSON.parse(process.argv[2]) : {};
+  process.stdout.write(JSON.stringify(getCloudflareUnenvConfig(input)));
+}

package/platform/src/shim/run.js

@@ -0,0 +1,25 @@
+import * as util from "@pulumi/pulumi";
+import { Link } from "../components/link";
+import { $config } from "../config";
+import { $transform, $asset } from "../components/component";
+
+const $secrets = JSON.parse(process.env.SST_SECRETS || "{}");
+const { output, apply, all, interpolate, concat, jsonParse, jsonStringify } =
+  util;
+
+const linkable = Link.makeLinkable;
+export {
+  linkable as "$linkable",
+  output as "$output",
+  apply as "$apply",
+  all as "$resolve",
+  interpolate as "$interpolate",
+  concat as "$concat",
+  jsonParse as "$jsonParse",
+  jsonStringify as "$jsonStringify",
+  util as "$util",
+  $asset as "$asset",
+  $config as "$config",
+  $transform as "$transform",
+  $secrets as "$secrets",
+};

package/platform/src/testing/global.ts

@@ -0,0 +1,83 @@
+import fs from "fs";
+import { createRequire } from "module";
+import path from "path";
+import { fileURLToPath } from "url";
+import { groups } from "../components/groups";
+
+/**
+ * The `sst` global a test is given: what SST's components share, and the
+ * components of each provider whose packages are installed. A config's `sst`
+ * has every group, and a deploy's bundle keeps the ones the app uses. A test
+ * loads what it's given without a bundler, so a group the app hasn't
+ * installed is left out, and says what to install when a test uses it.
+ */
+export async function sstGlobal(providers = groupProviders()) {
+  const sst: Record<string, unknown> = {
+    ...(await import("../components/core")),
+  };
+  for (const [name, load] of Object.entries(groups)) {
+    const missing = notInstalled(providers[name] ?? []);
+    if (missing.length === 0) {
+      sst[name] = await load();
+      continue;
+    }
+    Object.defineProperty(sst, name, {
+      enumerable: true,
+      get() {
+        const one = missing.length === 1;
+        throw new Error(
+          [
+            `sst.${name} needs ${list(missing)}, which ${
+              one ? "isn't" : "aren't"
+            } installed here.`,
+            `In a component package's repo, install ${
+              one ? "it as a dev dependency" : "them as dev dependencies"
+            }.`,
+            "In an app, use the sst/testing in .sst/platform, where SST's providers are installed.",
+          ].join(" "),
+        );
+      },
+    });
+  }
+  return sst;
+}
+
+function list(names: string[]) {
+  return names.length === 1
+    ? names[0]
+    : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The providers each group's components load, where the platform's
+ * package.json lists them: the one nearest this file, from its source or from
+ * the JavaScript the `sst` package has. Empty where they're all installed
+ * with the platform, as in an app's `.sst/platform` and the platform's own
+ * tests.
+ */
+function groupProviders(): Record<string, string[]> {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const file = path.join(dir, "package.json");
+    if (fs.existsSync(file))
+      return JSON.parse(fs.readFileSync(file, "utf8")).groups ?? {};
+    const parent = path.dirname(dir);
+    if (parent === dir) return {};
+    dir = parent;
+  }
+}
+
+/** Those of `names` that SST's components can't load */
+export function notInstalled(names: string[]) {
+  const require = createRequire(import.meta.url);
+  const found = (path: string) => {
+    try {
+      require.resolve(path);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  // A package's `exports` can hide either one from `require`
+  return names.filter((name) => !found(`${name}/package.json`) && !found(name));
+}

package/platform/src/testing/index.ts

@@ -0,0 +1,103 @@
+import fs from "fs";
+import * as pulumi from "@pulumi/pulumi";
+import { notInstalled, sstGlobal } from "./global";
+import { type MockInput, mockPulumi } from "./mock";
+
+export type { MockInput, RecordedResource } from "./mock";
+
+/**
+ * Test a component without deploying it. `mock()` stands in for the engine
+ * that deploys your app and gives your test what your `sst.config.ts` has:
+ * `sst`, your providers like `aws`, `$app`, `$dev` and the other `$` globals.
+ *
+ * Nothing is deployed and no provider is called. Each resource your component
+ * creates is recorded, with the inputs and options it was given, and comes
+ * back with an id and an ARN made from its name.
+ *
+ * Call it before the file that defines your component is loaded, if that
+ * file reads `sst` or `aws` when it loads. `sst/components` and the
+ * components of each provider, like `sst/components/aws`, can be imported
+ * anywhere.
+ *
+ * `sst` has the components of each provider whose packages are installed,
+ * like `sst.aws`. Using one that isn't fails, and says what to install.
+ *
+ * @example
+ * ```ts title="uploads.test.ts"
+ * import { expect, test } from "vitest";
+ * import { mock } from "./.sst/platform/src/testing";
+ *
+ * const app = await mock();
+ * const { Uploads } = await import("./infra/uploads");
+ *
+ * test("creates a role for each team", async () => {
+ *   app.reset();
+ *   new Uploads("Docs", { teams: ["design", "legal"] });
+ *   await app.settle();
+ *
+ *   expect(app.resources.map((r) => r.name)).toContain("DocsReaderLegal");
+ * });
+ * ```
+ */
+export async function mock(input?: MockInput & { dev?: boolean }) {
+  const engine = mockPulumi({ root: process.cwd(), ...input });
+
+  // What `sst.config.ts` is given when it's built: the app, and whether this
+  // is `sst dev`
+  Object.assign(globalThis, {
+    $app: {
+      name: input?.app ?? "app",
+      stage: input?.stage ?? "test",
+      removal: "remove",
+      providers: {},
+      protect: false,
+    },
+    $dev: input?.dev ?? false,
+  });
+
+  // The rest of the `$` globals. These are what `shim/run.js` gives a config.
+  const { Link } = await import("../components/link");
+  const { $asset, $transform } = await import("../components/component");
+  const { $config } = await import("../config");
+  Object.assign(globalThis, {
+    $linkable: Link.linkable,
+    $output: pulumi.output,
+    $apply: (pulumi as any).apply,
+    $resolve: pulumi.all,
+    $interpolate: pulumi.interpolate,
+    $concat: pulumi.concat,
+    $jsonParse: pulumi.jsonParse,
+    $jsonStringify: pulumi.jsonStringify,
+    $util: pulumi,
+    $asset,
+    $config,
+    $transform,
+    $secrets: {},
+  });
+
+  // Each provider under its name, and the components as `sst`
+  for (const provider of providers())
+    (globalThis as any)[provider.alias] = await import(provider.package);
+  (globalThis as any).sst = await sstGlobal();
+
+  return engine;
+}
+
+// The providers of the app, as `sst install` wrote them next to the platform.
+// Where there is no app, as in a component package's repo or the platform's
+// own tests, whichever of aws and cloudflare are installed.
+function providers(): { alias: string; package: string }[] {
+  try {
+    return JSON.parse(
+      fs.readFileSync(
+        new URL("../../../provider-lock.json", import.meta.url),
+        "utf8",
+      ),
+    );
+  } catch {
+    return [
+      { alias: "aws", package: "@pulumi/aws" },
+      { alias: "cloudflare", package: "@pulumi/cloudflare" },
+    ].filter((provider) => notInstalled([provider.package]).length === 0);
+  }
+}