vector-framework 1.0.0 → 1.2.0

package/src/types/standard-schema.ts

@@ -0,0 +1,147 @@
+/** The Standard Typed interface. This is a base type extended by other specs. */
+export interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly '~standard': StandardTypedV1.Props<Input, Output>;
+}
+
+export declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The Standard Typed types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Typed. */
+  export type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['input'];
+
+  /** Infers the output type of a Standard Typed. */
+  export type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+      options?: StandardSchemaV1.Options | undefined
+    ) => Result<Output> | Promise<Result<Output>>;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+
+  export interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard types interface. */
+  export interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+
+  /** Infers the input type of a Standard. */
+  export type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+
+  /** Infers the output type of a Standard. */
+  export type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+
+/** The Standard JSON Schema interface. */
+export interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard JSON Schema properties. */
+  readonly '~standard': StandardJSONSchemaV1.Props<Input, Output>;
+}
+
+export declare namespace StandardJSONSchemaV1 {
+  /** The Standard JSON Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Methods for generating the input/output JSON Schema. */
+    readonly jsonSchema: StandardJSONSchemaV1.Converter;
+  }
+
+  /** The Standard JSON Schema converter interface. */
+  export interface Converter {
+    /** Converts the input type to JSON Schema. May throw if conversion is not supported. */
+    readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+    /** Converts the output type to JSON Schema. May throw if conversion is not supported. */
+    readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+  }
+
+  /**
+   * The target version of the generated JSON Schema.
+   *
+   * It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`, as they are both in wide use. All other targets can be implemented on a best-effort basis. Libraries should throw if they don't support a specified target.
+   *
+   * The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0 which is a superset of JSON Schema `"draft-04"`.
+   */
+  export type Target =
+    | 'draft-2020-12'
+    | 'draft-07'
+    | 'openapi-3.0'
+    // Accepts any string: allows future targets while preserving autocomplete
+    | ({} & string);
+
+  /** The options for the input/output methods. */
+  export interface Options {
+    /** Specifies the target version of the generated JSON Schema. Support for all versions is on a best-effort basis. If a given version is not supported, the library should throw. */
+    readonly target: Target;
+
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+
+  /** The Standard types interface. */
+  export interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+
+  /** Infers the input type of a Standard. */
+  export type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+
+  /** Infers the output type of a Standard. */
+  export type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}

package/src/utils/cors.ts

@@ -0,0 +1,101 @@
+export interface CorsConfig {
+  origin: string | string[] | ((origin: string) => boolean);
+  credentials: boolean;
+  allowHeaders: string;
+  allowMethods: string;
+  exposeHeaders: string;
+  maxAge: number;
+}
+
+function getAllowedOrigin(origin: string | undefined, config: CorsConfig): string | null {
+  if (!origin) {
+    if (typeof config.origin === 'string') {
+      // Credentials cannot be combined with wildcard; only reflect concrete request origins.
+      if (config.origin === '*' && config.credentials) return null;
+      return config.origin;
+    }
+    return null;
+  }
+
+  if (typeof config.origin === 'string') {
+    if (config.origin === '*') {
+      return config.credentials ? origin : '*';
+    }
+    return config.origin === origin ? origin : null;
+  }
+  if (Array.isArray(config.origin)) {
+    return config.origin.includes(origin) ? origin : null;
+  }
+  if (typeof config.origin === 'function') {
+    return config.origin(origin) ? origin : null;
+  }
+  return null;
+}
+
+function shouldVaryByOrigin(config: CorsConfig): boolean {
+  return (
+    (typeof config.origin === 'string' && config.origin === '*' && config.credentials) ||
+    Array.isArray(config.origin) ||
+    typeof config.origin === 'function'
+  );
+}
+
+function buildCorsHeaders(origin: string | null, config: CorsConfig, varyByOrigin: boolean): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (origin) {
+    headers['access-control-allow-origin'] = origin;
+    headers['access-control-allow-methods'] = config.allowMethods;
+    headers['access-control-allow-headers'] = config.allowHeaders;
+    headers['access-control-expose-headers'] = config.exposeHeaders;
+    headers['access-control-max-age'] = String(config.maxAge);
+    if (config.credentials) {
+      headers['access-control-allow-credentials'] = 'true';
+    }
+    if (varyByOrigin) {
+      headers.vary = 'Origin';
+    }
+  }
+  return headers;
+}
+
+function mergeVary(existing: string | null, nextValue: string): string {
+  if (!existing) return nextValue;
+  const parts = existing
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean);
+  const lower = parts.map((v) => v.toLowerCase());
+  if (!lower.includes(nextValue.toLowerCase())) {
+    parts.push(nextValue);
+  }
+  return parts.join(', ');
+}
+
+export function cors(config: CorsConfig) {
+  return {
+    preflight(request: Request): Response {
+      const origin = request.headers.get('origin') ?? undefined;
+      const allowed = getAllowedOrigin(origin, config);
+      const varyByOrigin = Boolean(origin && allowed && shouldVaryByOrigin(config));
+      return new Response(null, {
+        status: 204,
+        headers: buildCorsHeaders(allowed, config, varyByOrigin),
+      });
+    },
+    corsify(response: Response, request: Request): Response {
+      const origin = request.headers.get('origin') ?? undefined;
+      const allowed = getAllowedOrigin(origin, config);
+      if (!allowed) return response;
+      const varyByOrigin = Boolean(origin && shouldVaryByOrigin(config));
+      const headers = buildCorsHeaders(allowed, config, varyByOrigin);
+      for (const [k, v] of Object.entries(headers)) {
+        if (k === 'vary') {
+          response.headers.set('vary', mergeVary(response.headers.get('vary'), v));
+          continue;
+        }
+        response.headers.set(k, v);
+      }
+      return response;
+    },
+  };
+}

package/src/utils/path.ts

@@ -1,9 +1,24 @@
 export function toFileUrl(path: string): string {
-  return process.platform === 'win32'
-    ? `file:///${path.replace(/\\/g, '/')}`
-    : path;
+  return process.platform === 'win32' ? `file:///${path.replace(/\\/g, '/')}` : path;
 }
 
 export function normalizePath(path: string): string {
   return path.replace(/\\/g, '/').replace(/\/+/g, '/');
-}
+}
+
+export function buildRouteRegex(path: string): RegExp {
+  return RegExp(
+    `^${path
+      .replace(/\/+(\/|$)/g, '$1')
+      .replace(/(\/?\.?):(\w+)\+/g, '($1(?<$2>[\\s\\S]+))')
+      .replace(/(\/?\.?):(\w+)/g, '($1(?<$2>[^$1/]+?))')
+      .replace(/\./g, '\\.')
+      .replace(/(\/?)\*/g, '($1.*)?')}/*$`
+  );
+}
+
+export default {
+  toFileUrl,
+  normalizePath,
+  buildRouteRegex,
+};

package/src/utils/schema-validation.ts

@@ -0,0 +1,123 @@
+import type { StandardRouteSchema } from '../types';
+
+export interface NormalizedValidationIssue {
+  message: string;
+  path: Array<string | number>;
+  code?: string;
+  raw?: unknown;
+}
+
+interface StandardValidationSuccess {
+  success: true;
+  value: unknown;
+}
+
+interface StandardValidationFailure {
+  success: false;
+  issues: readonly unknown[];
+}
+
+export type StandardValidationResult = StandardValidationSuccess | StandardValidationFailure;
+
+export function isStandardRouteSchema(schema: unknown): schema is StandardRouteSchema {
+  const standard = (schema as any)?.['~standard'];
+  return (
+    !!standard && typeof standard === 'object' && typeof standard.validate === 'function' && standard.version === 1
+  );
+}
+
+export async function runStandardValidation(
+  schema: StandardRouteSchema,
+  value: unknown
+): Promise<StandardValidationResult> {
+  const result = await schema['~standard'].validate(value);
+  const issues = (result as any)?.issues;
+
+  if (Array.isArray(issues) && issues.length > 0) {
+    return { success: false, issues };
+  }
+
+  return { success: true, value: (result as any)?.value };
+}
+
+export function extractThrownIssues(error: unknown): readonly unknown[] | null {
+  if (Array.isArray(error)) {
+    return error;
+  }
+
+  if (error && typeof error === 'object' && Array.isArray((error as any).issues)) {
+    return (error as any).issues;
+  }
+
+  if (error && typeof error === 'object' && (error as any).cause && Array.isArray((error as any).cause.issues)) {
+    return (error as any).cause.issues;
+  }
+
+  return null;
+}
+
+function normalizePath(path: unknown): Array<string | number> {
+  if (!Array.isArray(path)) return [];
+
+  const normalized: Array<string | number> = [];
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    let value = segment;
+
+    if (segment && typeof segment === 'object' && 'key' in (segment as any)) {
+      value = (segment as any).key;
+    }
+
+    if (typeof value === 'string' || typeof value === 'number') {
+      normalized.push(value);
+    } else if (typeof value === 'symbol') {
+      normalized.push(String(value));
+    } else if (value !== undefined && value !== null) {
+      normalized.push(String(value));
+    }
+  }
+
+  return normalized;
+}
+
+export function normalizeValidationIssues(
+  issues: readonly unknown[],
+  includeRawIssues: boolean
+): NormalizedValidationIssue[] {
+  const normalized: NormalizedValidationIssue[] = [];
+
+  for (let i = 0; i < issues.length; i++) {
+    const issue = issues[i];
+    const maybeIssue = issue as any;
+    const normalizedIssue: NormalizedValidationIssue = {
+      message:
+        typeof maybeIssue?.message === 'string' && maybeIssue.message.length > 0 ? maybeIssue.message : 'Invalid value',
+      path: normalizePath(maybeIssue?.path),
+    };
+
+    if (typeof maybeIssue?.code === 'string') {
+      normalizedIssue.code = maybeIssue.code;
+    }
+
+    if (includeRawIssues) {
+      normalizedIssue.raw = issue;
+    }
+
+    normalized.push(normalizedIssue);
+  }
+
+  return normalized;
+}
+
+export function createValidationErrorPayload(target: 'input' | 'output', issues: NormalizedValidationIssue[]) {
+  return {
+    error: true,
+    message: 'Validation failed',
+    statusCode: 422,
+    source: 'validation',
+    target,
+    issues,
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/utils/validation.ts

@@ -9,6 +9,7 @@ export function validateConfig(config: VectorConfig): VectorConfig {
     development: config.development || false,
     routesDir: config.routesDir || DEFAULT_CONFIG.ROUTES_DIR,
     autoDiscover: config.autoDiscover !== false,
+    defaults: config.defaults,
     cors: config.cors ? validateCorsOptions(config.cors) : undefined,
     before: config.before || [],
     finally: config.finally || [],