@vercel/config 0.0.9

package/dist/router.js

@@ -0,0 +1,484 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouter = exports.Router = exports.runtimeEnv = exports.param = void 0;
+const pretty_cache_header_1 = require("pretty-cache-header");
+const validation_1 = require("./utils/validation");
+/**
+ * Helper function to reference a path parameter in transforms.
+ * Path parameters are extracted from the route pattern (e.g., :userId).
+ *
+ * @example
+ * param('userId') // Returns '$userId'
+ */
+function param(name) {
+    return `$${name}`;
+}
+exports.param = param;
+/**
+ * Helper function to reference a runtime environment variable in transforms.
+ * These are environment variables that get resolved at request time by Vercel's routing layer,
+ * not at build time.
+ *
+ * @example
+ * runtimeEnv('BEARER_TOKEN') // Returns '$BEARER_TOKEN'
+ */
+function runtimeEnv(name) {
+    return `$${name}`;
+}
+exports.runtimeEnv = runtimeEnv;
+/**
+ * The main Router class for building a Vercel configuration object in code.
+ * Supports synchronous or asynchronous addition of rewrites, redirects, headers,
+ * plus convenience methods for crons, caching, and more.
+ */
+class Router {
+    constructor() {
+        this.redirectRules = [];
+        this.headerRules = [];
+        this.rewriteRules = [];
+        this.routeRules = [];
+        this.cronRules = [];
+        this.cleanUrlsConfig = undefined;
+        this.trailingSlashConfig = undefined;
+        this.buildCommandConfig = undefined;
+        this.installCommandConfig = undefined;
+    }
+    /**
+     * Helper to extract environment variable names from a string or string array.
+     * Environment variables are identified by the pattern $VAR_NAME where VAR_NAME
+     * is typically uppercase with underscores (e.g., $API_KEY, $BEARER_TOKEN).
+     */
+    extractEnvVars(args) {
+        const envVars = new Set();
+        const values = Array.isArray(args) ? args : [args];
+        for (const value of values) {
+            const matches = value.match(/\$([A-Z][A-Z0-9_]*)/g);
+            if (matches) {
+                for (const match of matches) {
+                    envVars.add(match.substring(1));
+                }
+            }
+        }
+        return Array.from(envVars);
+    }
+    /**
+     * Internal helper to convert TransformOptions to Transform array
+     */
+    transformOptionsToTransforms(options) {
+        const transforms = [];
+        // Convert requestHeaders
+        if (options.requestHeaders) {
+            for (const [key, value] of Object.entries(options.requestHeaders)) {
+                const envVars = this.extractEnvVars(value);
+                transforms.push({
+                    type: 'request.headers',
+                    op: 'set',
+                    target: { key },
+                    args: value,
+                    ...(envVars.length > 0 && { env: envVars }),
+                });
+            }
+        }
+        // Convert responseHeaders
+        if (options.responseHeaders) {
+            for (const [key, value] of Object.entries(options.responseHeaders)) {
+                const envVars = this.extractEnvVars(value);
+                transforms.push({
+                    type: 'response.headers',
+                    op: 'set',
+                    target: { key },
+                    args: value,
+                    ...(envVars.length > 0 && { env: envVars }),
+                });
+            }
+        }
+        // Convert requestQuery
+        if (options.requestQuery) {
+            for (const [key, value] of Object.entries(options.requestQuery)) {
+                const envVars = this.extractEnvVars(value);
+                transforms.push({
+                    type: 'request.query',
+                    op: 'set',
+                    target: { key },
+                    args: value,
+                    ...(envVars.length > 0 && { env: envVars }),
+                });
+            }
+        }
+        return transforms;
+    }
+    /**
+     * Adds a single rewrite rule (synchronous).
+     * Automatically enables rewrite caching by adding the x-vercel-enable-rewrite-caching header.
+     *
+     * @example
+     *    // This will automatically enable caching for the rewrite
+     *    import { createRouter, param, runtimeEnv } from '@vercel/router-sdk';
+     *    const router = createRouter();
+     *    router.rewrite('/api/(.*)', 'https://old-on-prem.com/$1')
+     *
+     *    // With transforms
+     *    router.rewrite('/users/:userId', 'https://api.example.com/users/$1', {
+     *      requestHeaders: {
+     *        'x-user-id': param('userId'),
+     *        'authorization': `Bearer ${runtimeEnv('API_TOKEN')}`
+     *      }
+     *    });
+     */
+    rewrite(source, destination, options) {
+        this.validateSourcePattern(source);
+        (0, validation_1.validateCaptureGroupReferences)(source, destination);
+        // Extract transform options
+        const { requestHeaders, responseHeaders, requestQuery, has, missing } = options || {};
+        const transformOpts = {
+            requestHeaders,
+            responseHeaders,
+            requestQuery,
+        };
+        // Convert to transforms if any transform options provided
+        const transforms = requestHeaders || responseHeaders || requestQuery
+            ? this.transformOptionsToTransforms(transformOpts)
+            : undefined;
+        this.rewriteRules.push({
+            source,
+            destination,
+            has,
+            missing,
+            transforms,
+        });
+        // Only enable rewrite caching for rewrites without transforms
+        // (transforms convert to routes, which don't need the caching header)
+        if (!transforms) {
+            this.headerRules.push({
+                source,
+                headers: [{ key: 'x-vercel-enable-rewrite-caching', value: '1' }],
+                has,
+                missing,
+            });
+        }
+        return this;
+    }
+    /**
+     * Loads rewrite rules asynchronously and appends them.
+     * Automatically enables rewrite caching for all loaded rules by adding the x-vercel-enable-rewrite-caching header.
+     *
+     * @example
+     *    // This will automatically enable caching for all rewrites
+     *    await router.rewrites(() => fetchRewriteRulesFromDB());
+     */
+    async rewrites(provider) {
+        const rules = await provider();
+        this.rewriteRules.push(...rules);
+        // Automatically enable rewrite caching for all rules
+        const headerRules = rules.map((rule) => ({
+            source: rule.source,
+            headers: [{ key: 'x-vercel-enable-rewrite-caching', value: '1' }],
+            has: rule.has,
+            missing: rule.missing,
+        }));
+        this.headerRules.push(...headerRules);
+        return this;
+    }
+    /**
+     * Adds a single redirect rule (synchronous).
+     * @example
+     *    router.redirect('/old-path', '/new-path', { permanent: true })
+     *
+     *    // With transforms
+     *    router.redirect('/users/:userId', '/new-users/$1', {
+     *      permanent: true,
+     *      requestHeaders: {
+     *        'x-user-id': param('userId')
+     *      }
+     *    })
+     */
+    redirect(source, destination, options) {
+        this.validateSourcePattern(source);
+        (0, validation_1.validateCaptureGroupReferences)(source, destination);
+        // Extract transform options
+        const { requestHeaders, responseHeaders, requestQuery, permanent, statusCode, has, missing, } = options || {};
+        // If transforms are provided, create a route instead of a redirect
+        if (requestHeaders || responseHeaders || requestQuery) {
+            const transformOpts = {
+                requestHeaders,
+                responseHeaders,
+                requestQuery,
+            };
+            const transforms = this.transformOptionsToTransforms(transformOpts);
+            this.routeRules.push({
+                src: source,
+                dest: destination,
+                transforms,
+                redirect: true,
+                status: statusCode || (permanent ? 308 : 307),
+                has,
+                missing,
+            });
+        }
+        else {
+            this.redirectRules.push({
+                source,
+                destination,
+                permanent,
+                statusCode,
+                has,
+                missing,
+            });
+        }
+        return this;
+    }
+    /**
+     * Loads redirect rules asynchronously and appends them.
+     */
+    async redirects(provider) {
+        const rules = await provider();
+        this.redirectRules.push(...rules);
+        return this;
+    }
+    /**
+     * Adds a single header rule (synchronous).
+     * @example
+     *    router.header('/api/(.*)', [{ key: 'X-Custom', value: 'HelloWorld' }])
+     */
+    header(source, headers, options) {
+        this.validateSourcePattern(source);
+        this.headerRules.push({ source, headers, ...options });
+        return this;
+    }
+    /**
+     * Loads header rules asynchronously and appends them.
+     */
+    async headers(provider) {
+        const rules = await provider();
+        this.headerRules.push(...rules);
+        return this;
+    }
+    /**
+     * Adds a typed "Cache-Control" header, leveraging `pretty-cache-header`.
+     * This method is purely for convenience, so you can do:
+     *
+     *   router.cacheControl('/my-page', {
+     *     public: true,
+     *     maxAge: '1week',
+     *     staleWhileRevalidate: '1year'
+     *   });
+     */
+    cacheControl(source, cacheOptions, options) {
+        const value = (0, pretty_cache_header_1.cacheHeader)(cacheOptions);
+        this.headerRules.push({
+            source,
+            headers: [{ key: 'Cache-Control', value }],
+            ...options,
+        });
+        return this;
+    }
+    /**
+     * Adds a route with transforms support.
+     * This is the newer, more powerful routing format that supports transforms.
+     *
+     * @example
+     *    // Add a route with transforms for path parameters and environment variables
+     *    router.route({
+     *      src: '/users/:userId/posts/:postId',
+     *      dest: 'https://api.example.com/users/$userId/posts/$postId',
+     *      transforms: [
+     *        {
+     *          type: 'request.headers',
+     *          op: 'set',
+     *          target: { key: 'x-user-id' },
+     *          args: '$userId'
+     *        },
+     *        {
+     *          type: 'request.headers',
+     *          op: 'set',
+     *          target: { key: 'authorization' },
+     *          args: 'Bearer $BEARER_TOKEN'
+     *        }
+     *      ]
+     *    });
+     */
+    route(config) {
+        this.validateSourcePattern(config.src);
+        this.routeRules.push(config);
+        return this;
+    }
+    /**
+     * When true, automatically serve HTML files and serverless functions
+     * without the .html or .js extension. This is a built-in Vercel feature.
+     */
+    setCleanUrls(value) {
+        this.cleanUrlsConfig = value;
+        return this;
+    }
+    /**
+     * When true, automatically normalize paths to include a trailing slash.
+     */
+    setTrailingSlash(value) {
+        this.trailingSlashConfig = value;
+        return this;
+    }
+    /**
+     * Sets a custom build command to run during deployment.
+     * @example
+     *   router.setBuildCommand('pnpm run generate-config')
+     */
+    setBuildCommand(value) {
+        this.buildCommandConfig = value;
+        return this;
+    }
+    /**
+     * Sets a custom install command to run during deployment.
+     * @example
+     *   router.setInstallCommand('pnpm install --no-frozen-lockfile')
+     */
+    setInstallCommand(value) {
+        this.installCommandConfig = value;
+        return this;
+    }
+    /**
+     * Adds a single cron rule (synchronous).
+     */
+    cron(path, schedule) {
+        this.validateCronExpression(schedule);
+        this.cronRules.push({ path, schedule });
+        return this;
+    }
+    /**
+     * Loads cron rules asynchronously and appends them.
+     */
+    async crons(provider) {
+        const rules = await provider();
+        this.cronRules.push(...rules);
+        return this;
+    }
+    /**
+     * Returns the complete router configuration.
+     * Typically, you'll export or return this in your build scripts,
+     * so that Vercel can pick it up.
+     */
+    getConfig() {
+        // Separate rewrites into those with and without transforms
+        const rewritesWithoutTransforms = this.rewriteRules.filter((r) => !r.transforms);
+        const rewritesWithTransforms = this.rewriteRules.filter((r) => r.transforms);
+        // Convert rewrites with transforms to routes
+        const routesFromRewrites = rewritesWithTransforms.map((rewrite) => {
+            const route = {
+                src: rewrite.source,
+                dest: rewrite.destination,
+                transforms: rewrite.transforms,
+            };
+            if (rewrite.has)
+                route.has = rewrite.has;
+            if (rewrite.missing)
+                route.missing = rewrite.missing;
+            return route;
+        });
+        // Combine with existing routes
+        const allRoutes = [...routesFromRewrites, ...this.routeRules];
+        // If routes exist, only return routes (not the legacy fields)
+        if (allRoutes.length > 0) {
+            const config = {
+                routes: allRoutes,
+            };
+            // Only include buildCommand/installCommand if they're explicitly set
+            if (this.buildCommandConfig !== undefined) {
+                config.buildCommand = this.buildCommandConfig;
+            }
+            if (this.installCommandConfig !== undefined) {
+                config.installCommand = this.installCommandConfig;
+            }
+            return config;
+        }
+        // Otherwise, return the legacy format
+        const config = {
+            redirects: this.redirectRules,
+            headers: this.headerRules,
+            rewrites: rewritesWithoutTransforms,
+            cleanUrls: this.cleanUrlsConfig,
+            trailingSlash: this.trailingSlashConfig,
+            crons: this.cronRules,
+        };
+        // Only include buildCommand/installCommand if they're explicitly set
+        if (this.buildCommandConfig !== undefined) {
+            config.buildCommand = this.buildCommandConfig;
+        }
+        if (this.installCommandConfig !== undefined) {
+            config.installCommand = this.installCommandConfig;
+        }
+        return config;
+    }
+    /**
+     * Visualizes the routing tree in the order that Vercel applies routes.
+     * Returns a formatted string showing the routing hierarchy.
+     */
+    visualize() {
+        const tree = [
+            {
+                type: 'Headers',
+                rules: this.headerRules,
+            },
+            {
+                type: 'Redirects',
+                rules: this.redirectRules,
+            },
+            {
+                type: 'Before Filesystem Rewrites',
+                rules: this.rewriteRules.filter((rewrite) => rewrite.source.startsWith('/api/') ||
+                    rewrite.source.startsWith('/_next/')),
+            },
+            {
+                type: 'Filesystem',
+                rules: [], // This would be populated by Vercel's filesystem routing
+            },
+            {
+                type: 'After Filesystem Rewrites',
+                rules: this.rewriteRules.filter((rewrite) => !rewrite.source.startsWith('/api/') &&
+                    !rewrite.source.startsWith('/_next/') &&
+                    rewrite.source !== '/(.*)'),
+            },
+            {
+                type: 'Fallback Rewrites',
+                rules: this.rewriteRules.filter((rewrite) => rewrite.source === '/(.*)'),
+            },
+        ];
+        return tree
+            .map((node) => {
+            const rules = node.rules.length > 0
+                ? node.rules
+                    .map((rule) => {
+                    if ('headers' in rule) {
+                        const headersStr = rule.headers
+                            .map((h) => `${h.key}: ${h.value}`)
+                            .join(', ');
+                        return `  ${rule.source} [${headersStr}]`;
+                    }
+                    if ('destination' in rule) {
+                        return `  ${rule.source} → ${rule.destination}`;
+                    }
+                    // @ts-ignore
+                    return `  ${rule.source}`;
+                })
+                    .join('\n')
+                : '  (empty)';
+            return `${node.type}:\n${rules}`;
+        })
+            .join('\n\n');
+    }
+    validateSourcePattern(source) {
+        (0, validation_1.validateRegexPattern)(source);
+    }
+    validateCronExpression(schedule) {
+        (0, validation_1.parseCronExpression)(schedule);
+    }
+}
+exports.Router = Router;
+/**
+ * A simple factory function for creating a new Router instance.
+ * @example
+ *   import { createRouter } from '@vercel/router-sdk';
+ *   const router = createRouter();
+ */
+function createRouter() {
+    return new Router();
+}
+exports.createRouter = createRouter;

package/dist/utils/validation.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Validates and type-checks regex patterns for Vercel's path-to-regexp syntax.
+ *
+ * @example
+ * // Valid patterns:
+ * "/api/(.*)"           // Basic capture group
+ * "/blog/:slug"         // Named parameter
+ * "/feedback/((?!general).*)" // Negative lookahead in a group
+ *
+ * // Invalid patterns:
+ * "/feedback/(?!general)" // Negative lookahead without group
+ * "[unclosed"            // Invalid regex syntax
+ * "/*"                   // Invalid wildcard pattern
+ */
+export declare function validateRegexPattern(pattern: string): string;
+/**
+ * Type for cron expression parts
+ */
+export type CronPart = {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+};
+/**
+ * Parses a cron expression into its parts
+ */
+export declare function parseCronExpression(expression: string): CronPart;
+/**
+ * Creates a type-safe cron expression builder
+ */
+export declare function createCronExpression(parts: CronPart): string;
+/**
+ * Counts the number of capture groups in a regex pattern.
+ * This includes both numbered groups (.*) and named parameters (:name).
+ */
+export declare function countCaptureGroups(pattern: string): number;
+/**
+ * Validates that a destination string doesn't reference capture groups
+ * that don't exist in the source pattern.
+ */
+export declare function validateCaptureGroupReferences(source: string, destination: string): void;

package/dist/utils/validation.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCaptureGroupReferences = exports.countCaptureGroups = exports.createCronExpression = exports.parseCronExpression = exports.validateRegexPattern = void 0;
+const zod_1 = require("zod");
+/**
+ * Validates and type-checks regex patterns for Vercel's path-to-regexp syntax.
+ *
+ * @example
+ * // Valid patterns:
+ * "/api/(.*)"           // Basic capture group
+ * "/blog/:slug"         // Named parameter
+ * "/feedback/((?!general).*)" // Negative lookahead in a group
+ *
+ * // Invalid patterns:
+ * "/feedback/(?!general)" // Negative lookahead without group
+ * "[unclosed"            // Invalid regex syntax
+ * "/*"                   // Invalid wildcard pattern
+ */
+function validateRegexPattern(pattern) {
+    // Check for common path-to-regexp syntax errors
+    if (pattern.includes("(?!") && !pattern.includes("((?!")) {
+        throw new Error(`Invalid path-to-regexp pattern: Negative lookaheads must be wrapped in a group. ` +
+            `Use "((?!pattern).*)" instead of "(?!pattern)". Pattern: ${pattern}`);
+    }
+    // Check for invalid wildcard patterns
+    if (pattern.includes("/*") || pattern.includes("/**")) {
+        throw new Error(`Invalid path-to-regexp pattern: Use '(.*)' instead of '*' for wildcards. ` +
+            `Pattern: ${pattern}`);
+    }
+    try {
+        // Test if it's a valid regex pattern
+        new RegExp(pattern);
+        return pattern;
+    }
+    catch (e) {
+        throw new Error(`Invalid regex pattern: ${pattern}`);
+    }
+}
+exports.validateRegexPattern = validateRegexPattern;
+/**
+ * Zod schema for validating cron expressions
+ */
+const cronPartSchema = zod_1.z.object({
+    minute: zod_1.z
+        .string()
+        .regex(/^(\*|[0-5]?[0-9]|\*\/[0-9]+|[0-5]?[0-9]-[0-5]?[0-9](,[0-5]?[0-9]-[0-5]?[0-9])*)$/),
+    hour: zod_1.z
+        .string()
+        .regex(/^(\*|1?[0-9]|2[0-3]|\*\/[0-9]+|1?[0-9]-1?[0-9]|2[0-3]-2[0-3](,1?[0-9]-1?[0-9]|,2[0-3]-2[0-3])*)$/),
+    dayOfMonth: zod_1.z
+        .string()
+        .regex(/^(\*|[1-2]?[0-9]|3[0-1]|\*\/[0-9]+|[1-2]?[0-9]-[1-2]?[0-9]|3[0-1]-3[0-1](,[1-2]?[0-9]-[1-2]?[0-9]|,3[0-1]-3[0-1])*)$/),
+    month: zod_1.z
+        .string()
+        .regex(/^(\*|[1-9]|1[0-2]|\*\/[0-9]+|[1-9]-[1-9]|1[0-2]-1[0-2](,[1-9]-[1-9]|,1[0-2]-1[0-2])*)$/),
+    dayOfWeek: zod_1.z
+        .string()
+        .regex(/^(\*|[0-6]|\*\/[0-9]+|[0-6]-[0-6](,[0-6]-[0-6])*)$/)
+});
+/**
+ * Parses a cron expression into its parts
+ */
+function parseCronExpression(expression) {
+    const parts = expression.split(" ");
+    if (parts.length !== 5) {
+        throw new Error("Invalid cron expression: must have 5 parts");
+    }
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+    return cronPartSchema.parse({
+        minute,
+        hour,
+        dayOfMonth,
+        month,
+        dayOfWeek
+    });
+}
+exports.parseCronExpression = parseCronExpression;
+/**
+ * Creates a type-safe cron expression builder
+ */
+function createCronExpression(parts) {
+    const validated = cronPartSchema.parse(parts);
+    return `${validated.minute} ${validated.hour} ${validated.dayOfMonth} ${validated.month} ${validated.dayOfWeek}`;
+}
+exports.createCronExpression = createCronExpression;
+/**
+ * Counts the number of capture groups in a regex pattern.
+ * This includes both numbered groups (.*) and named parameters (:name).
+ */
+function countCaptureGroups(pattern) {
+    let count = 0;
+    // Count regex capture groups (parentheses that aren't non-capturing)
+    const regex = /\((?!\?:)/g;
+    const matches = pattern.match(regex);
+    if (matches) {
+        count += matches.length;
+    }
+    // Count named parameters (:name)
+    const namedParams = pattern.match(/:[a-zA-Z_][a-zA-Z0-9_]*/g);
+    if (namedParams) {
+        count += namedParams.length;
+    }
+    return count;
+}
+exports.countCaptureGroups = countCaptureGroups;
+/**
+ * Validates that a destination string doesn't reference capture groups
+ * that don't exist in the source pattern.
+ */
+function validateCaptureGroupReferences(source, destination) {
+    const captureGroupCount = countCaptureGroups(source);
+    const references = destination.match(/\$(\d+)/g);
+    if (!references)
+        return;
+    for (const ref of references) {
+        const groupNum = parseInt(ref.substring(1), 10);
+        if (groupNum > captureGroupCount) {
+            throw new Error(`Invalid capture group reference: ${ref} used in destination "${destination}", ` +
+                `but source pattern "${source}" only has ${captureGroupCount} capture group(s). ` +
+                `Valid references are: ${Array.from({ length: captureGroupCount }, (_, i) => `$${i + 1}`).join(', ') || 'none'}`);
+        }
+    }
+}
+exports.validateCaptureGroupReferences = validateCaptureGroupReferences;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vercel/config",
+  "version": "0.0.9",
+  "description": "A TypeScript SDK for programmatically generating Vercel configuration files",
+  "bugs": {
+    "url": "https://github.com/vercel/router-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel/router-sdk"
+  },
+  "author": "Vercel",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "@vercel/config": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "pretty-cache-header": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.12",
+    "@types/node": "^18.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^2.8.0",
+    "typescript": "^4.9.0",
+    "vitest": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint . --ext .ts",
+    "release": "npm run build && changeset publish",
+    "test": "vitest",
+    "version-packages": "changeset version"
+  }
+}