alchemy 0.2.2 → 0.2.4

package/src/stripe/webhook.ts

@@ -86,6 +86,51 @@ export interface WebhookEndpoint
   status: string;
 }
 
+/**
+ * Create and manage Stripe webhook endpoints
+ *
+ * @example
+ * // Create a basic webhook for payment events
+ * const paymentWebhook = await WebhookEndpoint("payment-webhook", {
+ *   url: "https://api.example.com/stripe/payments",
+ *   enabledEvents: [
+ *     "payment_intent.succeeded",
+ *     "payment_intent.payment_failed"
+ *   ],
+ *   description: "Webhook for payment notifications"
+ * });
+ *
+ * @example
+ * // Create a webhook for subscription management
+ * const subscriptionWebhook = await WebhookEndpoint("subscription-webhook", {
+ *   url: "https://api.example.com/stripe/subscriptions",
+ *   enabledEvents: [
+ *     "customer.subscription.created",
+ *     "customer.subscription.updated",
+ *     "customer.subscription.deleted",
+ *     "invoice.payment_succeeded",
+ *     "invoice.payment_failed"
+ *   ],
+ *   description: "Webhook for subscription lifecycle events"
+ * });
+ *
+ * @example
+ * // Create a webhook for Connect platform events
+ * const connectWebhook = await WebhookEndpoint("connect-webhook", {
+ *   url: "https://api.example.com/stripe/connect",
+ *   enabledEvents: [
+ *     "account.updated",
+ *     "account.application.deauthorized",
+ *     "payout.created",
+ *     "payout.failed"
+ *   ],
+ *   connect: true,
+ *   metadata: {
+ *     platform: "connect",
+ *     environment: "production"
+ *   }
+ * });
+ */
 export const WebhookEndpoint = Resource(
   "stripe::WebhookEndpoint",
   async function (

package/src/test/bun.ts

@@ -6,35 +6,111 @@ import { alchemy } from "../alchemy";
 import { destroy } from "../destroy";
 import type { Scope } from "../scope";
 
+/**
+ * Extend the Alchemy interface to include test functionality
+ */
 declare module "../alchemy" {
   interface Alchemy {
     test: typeof test;
   }
 }
 
+/**
+ * Add test functionality to alchemy instance
+ */
 alchemy.test = test;
 
+/**
+ * Options for configuring test behavior
+ */
 export interface TestOptions {
+  /**
+   * Whether to automatically destroy resources after test.
+   * @default true.
+   */
   destroy?: boolean;
+
+  /**
+   * Whether to suppress logging output.
+   * @default false.
+   */
   quiet?: boolean;
+
+  /**
+   * Password to use for test resources.
+   * @default "test-password".
+   */
   password?: string;
 }
 
+/**
+ * Global test scope for all tests
+ */
 const globalTestScope = alchemy.scope("test");
 
+/**
+ * Test function type definition with overloads
+ */
 type test = {
+  /**
+   * Create a test with default options
+   * @param name Test name
+   * @param fn Test function
+   * @param timeout Optional timeout in milliseconds
+   */
   (name: string, fn: (scope: Scope) => Promise<any>, timeout?: number): void;
+
+  /**
+   * Create a test with custom options
+   * @param name Test name
+   * @param options Test configuration options
+   * @param fn Test function
+   * @param timeout Optional timeout in milliseconds
+   */
   (
     name: string,
     options: TestOptions,
     fn: (scope: Scope) => Promise<any>,
     timeout?: number,
   ): void;
+
+  /**
+   * Skip test conditionally
+   * @param condition If true, test will be skipped
+   */
   skipIf(condition: boolean): test;
+
+  /**
+   * Current test scope
+   */
   scope: Scope;
 };
 
+/**
+ * Creates a test helper function that provides scoped resource management
+ *
+ * @param meta Import meta object from the test file
+ * @param defaultOptions Default options to apply to all tests
+ * @returns Test function with scope management
+ *
+ * @example
+ * ```typescript
+ * const test = alchemy.test(import.meta);
+ *
+ * describe("My Resource", () => {
+ *   test("create and delete", async (scope) => {
+ *     try {
+ *       const resource = await MyResource("test", { ... });
+ *       expect(resource.id).toBeTruthy();
+ *     } finally {
+ *       await alchemy.destroy(scope);
+ *     }
+ *   });
+ * });
+ * ```
+ */
 export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
+  // Add skipIf functionality
   test.skipIf = (condition: boolean) => {
     if (condition) {
       // TODO: proxy through to bun:test.skipIf
@@ -43,11 +119,13 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
     return test;
   };
 
+  // Create local test scope based on filename
   const localTestScope = alchemy.scope(path.basename(meta.filename), {
     parent: globalTestScope,
   });
   test.scope = localTestScope;
 
+  // Clean up test scope after all tests complete
   afterAll(() => alchemy.destroy(test.scope));
 
   return test as any;
@@ -71,13 +149,16 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
             ),
           )
         : {};
+
+    // Merge options with defaults
     const options = {
-      destroy: false,
+      destroy: true,
       quiet: false,
       password: "test-password",
       ...spread(defaultOptions),
       ...spread(_options),
     };
+
     const fn = typeof args[1] === "function" ? args[1] : args[2]!;
 
     return alchemy.run(
@@ -88,13 +169,12 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
       },
       async (scope) => {
         return it(testName, async () => {
-          // bun will call from a different scope, so we need to enter the test's scope manually
+          // Enter test scope since bun calls from different scope
           scope.enter();
           try {
             await fn(scope);
           } finally {
             if (options.destroy !== false) {
-              // TODO: auto-destroy resources
               await destroy(scope);
             }
           }

package/src/util/serde.ts

@@ -2,15 +2,39 @@ import { Scope } from "../scope";
 import { Secret } from "../secret";
 import { decryptWithKey, encryptWithKey } from "./encrypt";
 
-export async function serialize(scope: Scope, value: any): Promise<any> {
+import type { Type } from "arktype";
+
+// zero-dependency type guard for ArkType
+function isType(value: any): value is Type<any, any> {
+  return (
+    value &&
+    typeof value === "object" &&
+    typeof value.toJsonSchema === "function"
+  );
+}
+
+export async function serialize(
+  scope: Scope,
+  value: any,
+  options?: {
+    encrypt?: boolean;
+  },
+): Promise<any> {
   if (Array.isArray(value)) {
-    return Promise.all(value.map((value) => serialize(scope, value)));
+    return Promise.all(value.map((value) => serialize(scope, value, options)));
   } else if (value instanceof Secret) {
     if (!scope.password) {
       throw new Error("Cannot serialize secret without password");
     }
     return {
-      "@secret": await encryptWithKey(value.unencrypted, scope.password),
+      "@secret":
+        options?.encrypt !== false
+          ? await encryptWithKey(value.unencrypted, scope.password)
+          : value.unencrypted,
+    };
+  } else if (isType(value)) {
+    return {
+      "@schema": value.toJSON(),
     };
   } else if (value instanceof Scope) {
     return undefined;
@@ -19,7 +43,7 @@ export async function serialize(scope: Scope, value: any): Promise<any> {
       await Promise.all(
         Object.entries(value).map(async ([key, value]) => [
           key,
-          await serialize(scope, value),
+          await serialize(scope, value, options),
         ]),
       ),
     );
@@ -38,6 +62,8 @@ export async function deserialize(scope: Scope, value: any): Promise<any> {
         throw new Error("Cannot deserialize secret without password");
       }
       return new Secret(await decryptWithKey(value["@secret"], scope.password));
+    } else if ("@schema" in value) {
+      return value["@schema"];
     } else {
       return Object.fromEntries(
         await Promise.all(

package/src/vitepress/dependencies.ts

@@ -0,0 +1,68 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+
+const execAsync = promisify(exec);
+
+export type InstallDependencies = Resource<"project::InstallDependencies">;
+
+export const InstallDependencies = Resource(
+  "project::InstallDependencies",
+  {
+    alwaysUpdate: true,
+  },
+  async function (
+    this: Context<InstallDependencies>,
+    id: string,
+    {
+      cwd,
+      dependencies,
+      devDependencies,
+    }: {
+      cwd: string;
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    },
+  ) {
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    await installDependencies(cwd, dependencies);
+    await installDependencies(cwd, devDependencies, "-D");
+    await execAsync("bun install", { cwd });
+
+    return this({});
+  },
+);
+
+function isInstallableVersion(version: string) {
+  // TODO: file:// ?
+  return !version.startsWith("workspace:");
+}
+
+export function fixedDependencies(dependencies?: Record<string, string>) {
+  if (!dependencies) return {};
+  return Object.fromEntries(
+    Object.entries(dependencies).filter(
+      ([, value]) => !isInstallableVersion(value),
+    ),
+  );
+}
+
+export async function installDependencies(
+  cwd: string,
+  dependencies: Record<string, string> | undefined,
+  ...args: string[]
+) {
+  if (!dependencies) return;
+  const deps = Object.entries(dependencies)
+    .filter(([, value]) => isInstallableVersion(value))
+    .map(([pkg, version]) => `${pkg}@${version}`)
+    .join(" ");
+
+  const cmd = `bun add ${args.join(" ")} ${deps}`;
+  console.log(cmd);
+  await execAsync(cmd, { cwd });
+}

package/src/vitepress/home-page.ts

@@ -0,0 +1,166 @@
+import yaml from "yaml";
+
+/**
+ * Image that can be themed for light/dark mode
+ */
+export interface ThemeableImage {
+  /**
+   * Image source URL
+   */
+  src?: string;
+
+  /**
+   * Image alt text
+   */
+  alt?: string;
+
+  /**
+   * Light theme image URL
+   */
+  light?: string;
+
+  /**
+   * Dark theme image URL
+   */
+  dark?: string;
+}
+
+/**
+ * Hero action button configuration
+ */
+export interface HeroAction {
+  /**
+   * Color theme of the button
+   * @default "brand"
+   */
+  theme?: "brand" | "alt";
+
+  /**
+   * Label of the button
+   */
+  text: string;
+
+  /**
+   * Destination link of the button
+   */
+  link: string;
+
+  /**
+   * Link target attribute
+   */
+  target?: string;
+
+  /**
+   * Link rel attribute
+   */
+  rel?: string;
+}
+
+/**
+ * Hero section configuration
+ */
+export interface Hero {
+  /**
+   * The string shown top of text. Comes with brand color
+   * and expected to be short, such as product name.
+   */
+  name?: string;
+
+  /**
+   * The main text for the hero section. This will be defined
+   * as h1 tag.
+   */
+  text: string;
+
+  /**
+   * Tagline displayed below text
+   */
+  tagline?: string;
+
+  /**
+   * The image displayed next to the text and tagline area
+   */
+  image?: string | ThemeableImage;
+
+  /**
+   * Action buttons to display in home hero section
+   */
+  actions?: HeroAction[];
+}
+
+/**
+ * Feature item configuration
+ */
+export interface Feature {
+  /**
+   * Show icon on each feature box
+   */
+  icon?: string | ThemeableImage;
+
+  /**
+   * Title of the feature
+   */
+  title: string;
+
+  /**
+   * Details of the feature
+   */
+  details: string;
+
+  /**
+   * Link when clicked on feature component
+   */
+  link?: string;
+
+  /**
+   * Link text to be shown inside feature component
+   */
+  linkText?: string;
+
+  /**
+   * Link rel attribute
+   */
+  rel?: string;
+
+  /**
+   * Link target attribute
+   */
+  target?: string;
+}
+
+/**
+ * VitePress home page configuration
+ */
+export interface HomePage {
+  /**
+   * Use home page layout
+   */
+  layout: "home";
+
+  /**
+   * Hero section configuration
+   */
+  hero?: Hero;
+
+  /**
+   * Features section configuration
+   */
+  features?: Feature[];
+
+  /**
+   * Whether to apply default markdown styles
+   * @default true
+   */
+  markdownStyles?: boolean;
+}
+
+/**
+ * Parse YAML frontmatter to home page config
+ */
+export function parseHomePage(content: string): HomePage {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error("Invalid frontmatter format");
+  }
+  return yaml.parse(match[1]) as HomePage;
+}

package/src/vitepress/index.md

@@ -0,0 +1,75 @@
+# Docs Index
+
+```ts twoslash
+// @noErrors
+import path from "path";
+
+import alchemy, { Resource, Context } from "alchemy";
+
+import { Zone } from "alchemy/cloudflare";
+
+type alchemy = any;
+
+await using app = alchemy("github:alchemy", {
+  //          ^?
+  stage: "prod",
+  phase: process.argv.includes("--destroy") ? "destroy" : "up",
+  // pass the password in (you can get it from anywhere, e.g. stdin)
+  password: process.env.SECRET_PASSPHRASE,
+  quiet: process.argv.includes("--verbose") ? false : true,
+});
+
+export interface Product {}
+
+export const Product = Resource(
+  "stripe::Product",
+  async function (
+    this: Context<any>,
+    id: string,
+    props: any,
+  ): Promise<Product> {
+    this.
+    //   ^|
+  }
+);
+```
+
+```ts twoslash
+// @noErrors
+// @esModuleInterop
+import express from "express"
+const app = {
+  get(path: string, fn: (req: any, res: { send(): void }))
+}
+app.get("/", function (req, res) {
+  res.sen
+//       ^|
+})
+app.listen(3000)
+```
+
+```ts twoslash
+// @module: esnext
+// @filename: maths.ts
+export function absolute(num: number) {
+  if (num < 0) return num * -1;
+  return num;
+}
+// @filename: index.ts
+import { absolute } from "./maths";
+const value = absolute(-1);
+```
+
+```ts twoslash
+// @module: esnext
+// @filename: maths.ts
+export function absolute(num: number) {
+  if (num < 0) return num * -1;
+  return num;
+}
+// @filename: index.ts
+// ---cut---
+import { absolute } from "./maths";
+const value = absolute(-1);
+//    ^?
+```

package/src/vitepress/index.ts

@@ -0,0 +1,2 @@
+export * from "./home-page";
+export * from "./vitepress";