convex-rust 0.0.0-stage → 0.1.1

package/dist/cli/build.d.ts

@@ -0,0 +1,146 @@
+import { RustManifestEntry } from "./manifest.js";
+import { WasiSdkMode } from "./wasisdk.js";
+export type Profile = "dev" | "release";
+export interface BuildOptions {
+    /** Project root (default: cwd). */
+    cwd: string;
+    /** Crate directory (default `<functions>/rust`). */
+    crate?: string;
+    /** Output directory (default `<functions>/rust`). */
+    out?: string;
+    profile: Profile;
+    /** Env var names the guest may read (emitted into the wrappers). */
+    env?: string[];
+    /** Compile with `-C target-feature=+simd128` (default true; `--no-simd` / `CONVEX_RUST_SIMD=0` opt out). */
+    simd?: boolean;
+    /**
+     * One wasm per Convex module (`--split` / `CONVEX_RUST_SPLIT=1`): wasm-opt drops the code only the other
+     * modules need, so each action loads (and the platform compiles, on every call) less. Needs wasm-opt.
+     */
+    split?: boolean;
+    /**
+     * Module groups (`--group name=modA,modB`): the crate is built once per group with
+     * `--no-default-features --features <prefix><module>,...` (see {@link GROUP_FEATURE_PREFIX}), so a group's
+     * wasm contains only its modules' functions and dependencies. Each module imports its group's wasm.
+     */
+    groups?: ModuleGroup[];
+    /** Cargo feature name prefix for the group builds (default `m-`). */
+    groupFeaturePrefix?: string;
+    /**
+     * Default true: with no explicit groups, build one wasm per Convex module: through the crate's `m-<module>`
+     * features when it defines two or more (see {@link modulesFromFeatures}), else zero-config through the
+     * `#[action]` macro's `convex_split` cfg (see {@link splitRustcArgs}). `false` (`--single` / `CONVEX_RUST_MODULES=0`)
+     * builds one shared wasm with the default features. The zero-config split (no `m-` features) is skipped in the
+     * dev profile (`convex-rust dev`: ~8x slower rebuilds) unless this is `true` (`--modules` / `CONVEX_RUST_MODULES=1`).
+     */
+    perModule?: boolean;
+    /**
+     * C compiler for crates that build C code: "auto" (default) uses a wasi-sdk found via `WASI_SDK_PATH` or the cache dir
+     * and downloads one only when a dependency has a C build script; "always" downloads it; "never" leaves cc-rs alone.
+     */
+    wasiSdk?: WasiSdkMode;
+    /** Total wasm size above which the smallest zero-config modules are merged (default {@link WASM_BUDGET_BYTES}). */
+    wasmBudget?: number;
+    log?: (msg: string) => void;
+}
+export declare class BuildError extends Error {
+}
+export interface ModuleGroup {
+    name: string;
+    /** Convex module names (`cpu`, `a/b`). */
+    modules: string[];
+}
+export declare const GROUP_FEATURE_PREFIX = "m-";
+/** Parses `--group name=modA,modB` values. Throws {@link BuildError} on a malformed or overlapping spec. */
+export declare function parseGroups(specs: string[]): ModuleGroup[];
+/**
+ * Convex module names for the crate's `<prefix><module>` features (`m-a-b` -> `a/b`: Rust module names have
+ * no dashes, so a dash is a path separator). Sorted; empty when the crate has fewer than two such features
+ * (one feature gates nothing worth splitting).
+ */
+export declare function modulesFromFeatures(features: string[], prefix?: string): string[];
+/** File-name stem of a module's wasm: the module with `/` as `__`. */
+export declare function moduleFileName(module: string): string;
+/** Rejects modules whose wasm file names collide (`a/b` and a real module `a__b` would overwrite each other). */
+export declare function assertDistinctFileNames(modules: Iterable<string>): void;
+/** One group per module; the group (file) name is the module with `/` as `__`. */
+export declare function perModuleGroups(modules: string[]): ModuleGroup[];
+/** Cargo feature args that build only a group's modules. Module `a/b` maps to feature `<prefix>a-b`. */
+export declare function groupFeatureArgs(group: ModuleGroup, prefix?: string): string[];
+/** Wasm size budget for all per-module wasm together: Convex bundles at most 32 MiB of code per deployment. */
+export declare const WASM_BUDGET_BYTES: number;
+/**
+ * Zero-config per-module build: the extra `rustc` arguments (after `cargo rustc ... --`) that make the
+ * `#[action]` macro keep only the exports of `fns` (see `crates/convex_fn_macros`). `--check-cfg` keeps
+ * the `unexpected_cfgs` lint quiet for crates that do not otherwise declare these cfgs.
+ */
+export declare function splitRustcArgs(fns: string[]): string[];
+/** The two smallest entries of `sizes` (the next merge candidates when over the size budget), or undefined. */
+export declare function smallestTwo(sizes: Map<string, number>): [string, string] | undefined;
+/** Convex functions directory: `functions` in convex.json, default `convex`. */
+export declare function resolveFunctionsDir(cwd: string): string;
+export declare function cargoProfileDir(profile: Profile): string;
+/** Cargo args and env for a profile; the dev profile is defined via env. */
+export declare function cargoBuildConfig(profile: Profile): {
+    args: string[];
+    env: Record<string, string>;
+};
+/** Rust flag pair that turns on wasm SIMD. */
+export declare const SIMD_RUSTFLAG = "target-feature=+simd128";
+/**
+ * Extra cargo args / env for the SIMD option. With RUSTFLAGS (or CARGO_ENCODED_RUSTFLAGS) set the flag is
+ * appended to it; otherwise it goes in as `--config target.<triple>.rustflags`, which cargo joins with the
+ * rustflags of every `.cargo/config.toml` `target.<triple>.rustflags` (a config `build.rustflags` is then
+ * shadowed, as for any target-specific rustflags).
+ */
+export declare function simdCargoConfig(simd: boolean, env?: Record<string, string | undefined>): {
+    args: string[];
+    env: Record<string, string>;
+};
+/** Cargo target directory and library name of the crate, via `cargo metadata`. */
+export declare function findCrateLayout(crateDir: string): Promise<{
+    targetDir: string;
+    libName: string;
+    features: string[];
+}>;
+/** Crates of the wasm32-wasip1 dependency graph whose build script drives a C compiler (`cc` / `cmake`). */
+export declare function cBuildCrates(crateDir: string): Promise<string[]>;
+export declare function wasmOptFlags(): string[];
+/**
+ * `wasm-opt -O3` when available, with a content-addressed cache in
+ * `cacheDir`. Returns the bytes to ship (the input when wasm-opt is missing,
+ * fails, does not shrink the module or drops the manifest). `onNames` receives the function names
+ * (index in the returned module -> raw name) for the symbol map.
+ */
+export declare function optimizeWasm(input: Uint8Array, cacheDir: string, log?: (m: string) => void, onNames?: (names: Map<number, string>) => void): Uint8Array;
+/** The stock bundler walks every file of the functions directory; cargo output there is a hazard. */
+export declare function warnIfTargetInsideFunctions(targetDir: string, functionsDir: string, log: (m: string) => void): void;
+export interface WriteResult {
+    written: string[];
+    removed: string[];
+}
+/** Writes the generated files and the wasm; removes stale generated files. */
+export declare function writeOutput(outDir: string, wasmFile: string, wasm: Uint8Array, entries: RustManifestEntry[], functionsDir: string, env?: string[], split?: Map<string, Uint8Array>, grouped?: {
+    wasm: Map<string, Uint8Array>;
+    moduleGroup: Map<string, string>;
+}): WriteResult;
+export interface BuildResult extends WriteResult {
+    wasmFile: string;
+    functions: string[];
+    outDir: string;
+}
+/** Builds the crate and writes the generated files. Throws {@link BuildError}. */
+export declare function buildOnce(opts: BuildOptions): Promise<BuildResult>;
+/** Should a change to this crate-relative path trigger a rebuild? */
+export declare function isWatchedChange(relPath: string): boolean;
+/** Should a change to this functions-dir-relative path re-run the api.rs codegen? */
+export declare function isTsSourceChange(relPath: string): boolean;
+/**
+ * Initial build, then rebuild on changes to the crate sources (and re-run the api.rs codegen on
+ * TypeScript changes). Events are debounced, and only a real content change versus the state
+ * after the last build triggers a rebuild, so the build's own writes (Cargo.lock, the managed
+ * config block, api.rs) never loop. Never resolves.
+ */
+export declare function watch(opts: BuildOptions): Promise<never>;
+/** Regenerates only `src/_generated/api.rs` (no cargo). Needs a previous build for the Rust functions. */
+export declare function codegenOnly(opts: BuildOptions): Promise<boolean>;