vector-framework 1.2.0 → 1.2.2

package/src/openapi/generator.ts

@@ -131,18 +131,25 @@ function convertInputSchema(
   warnings: string[]
 ): JsonSchema | null {
   if (!isJSONSchemaCapable(inputSchema)) {
-    return null;
+    const fallback = buildFallbackJSONSchema(inputSchema);
+    return isEmptyObjectSchema(fallback) ? null : fallback;
   }
 
   try {
     return inputSchema['~standard'].jsonSchema.input({ target });
   } catch (error) {
+    const alternate = tryAlternateTargetConversion(inputSchema, 'input', target, error, routePath, undefined, warnings);
+    if (alternate) {
+      return alternate;
+    }
+
     warnings.push(
       `[OpenAPI] Failed input schema conversion for ${routePath}: ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }. Falling back to a permissive JSON Schema.`
     );
-    return null;
+    const fallback = buildFallbackJSONSchema(inputSchema);
+    return isEmptyObjectSchema(fallback) ? null : fallback;
   }
 }
 
@@ -154,18 +161,32 @@ function convertOutputSchema(
   warnings: string[]
 ): JsonSchema | null {
   if (!isJSONSchemaCapable(outputSchema)) {
-    return null;
+    const fallback = buildFallbackJSONSchema(outputSchema);
+    return isEmptyObjectSchema(fallback) ? null : fallback;
   }
 
   try {
     return outputSchema['~standard'].jsonSchema.output({ target });
   } catch (error) {
+    const alternate = tryAlternateTargetConversion(
+      outputSchema,
+      'output',
+      target,
+      error,
+      routePath,
+      statusCode,
+      warnings
+    );
+    if (alternate) {
+      return alternate;
+    }
+
     warnings.push(
       `[OpenAPI] Failed output schema conversion for ${routePath} (${statusCode}): ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }. Falling back to a permissive JSON Schema.`
     );
-    return null;
+    return buildFallbackJSONSchema(outputSchema);
   }
 }
 
@@ -173,6 +194,320 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
+function isEmptyObjectSchema(value: unknown): value is Record<string, never> {
+  return isRecord(value) && Object.keys(value).length === 0;
+}
+
+function tryAlternateTargetConversion(
+  schema: unknown,
+  kind: 'input' | 'output',
+  target: string,
+  originalError: unknown,
+  routePath: string,
+  statusCode: string | undefined,
+  warnings: string[]
+): JsonSchema | null {
+  if (!isJSONSchemaCapable(schema)) {
+    return null;
+  }
+
+  const message = originalError instanceof Error ? originalError.message : String(originalError);
+  const unsupportedOpenAPITarget =
+    target === 'openapi-3.0' &&
+    message.includes("target 'openapi-3.0' is not supported") &&
+    message.includes('draft-2020-12') &&
+    message.includes('draft-07');
+
+  if (!unsupportedOpenAPITarget) {
+    return null;
+  }
+
+  try {
+    const converted = schema['~standard'].jsonSchema[kind]({ target: 'draft-07' });
+    warnings.push(
+      kind === 'input'
+        ? `[OpenAPI] ${routePath} converter does not support openapi-3.0 target; using draft-07 conversion output.`
+        : `[OpenAPI] ${routePath} (${statusCode}) converter does not support openapi-3.0 target; using draft-07 conversion output.`
+    );
+    return converted;
+  } catch {
+    return null;
+  }
+}
+
+// Best-effort extraction of internal schema definition metadata from common
+// standards-compatible validators. If unavailable, callers should fall back to {}.
+function getValidatorSchemaDef(schema: unknown): Record<string, unknown> | null {
+  if (!schema || typeof schema !== 'object') return null;
+  const value = schema as Record<string, any>;
+  if (isRecord(value._def)) return value._def as Record<string, unknown>;
+  if (isRecord(value._zod) && isRecord((value._zod as Record<string, any>).def)) {
+    return (value._zod as Record<string, any>).def as Record<string, unknown>;
+  }
+  if (value.kind === 'schema' && typeof value.type === 'string') {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+function getSchemaKind(def: Record<string, unknown> | null): string | null {
+  if (!def) return null;
+  const typeName = def.typeName;
+  if (typeof typeName === 'string') return typeName;
+  const type = def.type;
+  if (typeof type === 'string') return type;
+  return null;
+}
+
+function pickSchemaChild(def: Record<string, unknown>): unknown {
+  const candidates = ['innerType', 'schema', 'type', 'out', 'in', 'left', 'right', 'wrapped', 'element'];
+  for (const key of candidates) {
+    if (key in def) return (def as Record<string, unknown>)[key];
+  }
+  return undefined;
+}
+
+function pickSchemaObjectCandidate(def: Record<string, unknown>, keys: string[]): unknown {
+  for (const key of keys) {
+    const value = (def as Record<string, unknown>)[key];
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function isOptionalWrapperKind(kind: string | null): boolean {
+  if (!kind) return false;
+  const lower = kind.toLowerCase();
+  return lower.includes('optional') || lower.includes('default') || lower.includes('catch');
+}
+
+function unwrapOptionalForRequired(schema: unknown): { schema: unknown; optional: boolean } {
+  let current = schema;
+  let optional = false;
+  let guard = 0;
+  while (guard < 8) {
+    guard += 1;
+    const def = getValidatorSchemaDef(current);
+    const kind = getSchemaKind(def);
+    if (!def || !isOptionalWrapperKind(kind)) break;
+    optional = true;
+    const inner = pickSchemaChild(def);
+    if (!inner) break;
+    current = inner;
+  }
+  return { schema: current, optional };
+}
+
+function getObjectShape(def: Record<string, unknown>): Record<string, unknown> {
+  const entries = (def as Record<string, any>).entries;
+  if (isRecord(entries)) {
+    return entries as Record<string, unknown>;
+  }
+
+  const rawShape = (def as Record<string, any>).shape;
+  if (typeof rawShape === 'function') {
+    try {
+      const resolved = rawShape();
+      return isRecord(resolved) ? (resolved as Record<string, unknown>) : {};
+    } catch {
+      return {};
+    }
+  }
+  return isRecord(rawShape) ? (rawShape as Record<string, unknown>) : {};
+}
+
+function extractEnumValues(def: Record<string, unknown>): unknown[] {
+  const values = (def as Record<string, any>).values;
+  if (Array.isArray(values)) return values;
+  if (values && typeof values === 'object') return Object.values(values as Record<string, unknown>);
+
+  const entries = (def as Record<string, any>).entries;
+  if (entries && typeof entries === 'object') return Object.values(entries as Record<string, unknown>);
+
+  const enumObject = (def as Record<string, any>).enum;
+  if (enumObject && typeof enumObject === 'object') return Object.values(enumObject as Record<string, unknown>);
+
+  const options = (def as Record<string, any>).options;
+  if (Array.isArray(options)) {
+    return options
+      .map((item) => {
+        if (item && typeof item === 'object' && 'unit' in (item as Record<string, unknown>)) {
+          return (item as Record<string, unknown>).unit;
+        }
+        return item;
+      })
+      .filter((item) => item !== undefined);
+  }
+
+  return [];
+}
+
+function mapPrimitiveKind(kind: string): JsonSchema | null {
+  const lower = kind.toLowerCase();
+  if (lower.includes('string')) return { type: 'string' };
+  if (lower.includes('number')) return { type: 'number' };
+  if (lower.includes('boolean')) return { type: 'boolean' };
+  if (lower.includes('bigint')) return { type: 'string' };
+  if (lower === 'null' || lower.includes('zodnull')) return { type: 'null' };
+  if (lower.includes('any') || lower.includes('unknown') || lower.includes('never')) return {};
+  if (lower.includes('date')) return { type: 'string', format: 'date-time' };
+  if (lower.includes('custom')) return { type: 'object', additionalProperties: true };
+  return null;
+}
+
+// Universal fallback schema builder used when converter functions throw.
+// This keeps docs generation resilient and preserves routes in OpenAPI output.
+function buildIntrospectedFallbackJSONSchema(schema: unknown, seen: WeakSet<object> = new WeakSet()): JsonSchema {
+  if (!schema || typeof schema !== 'object') return {};
+  if (seen.has(schema as object)) return {};
+  seen.add(schema as object);
+
+  const def = getValidatorSchemaDef(schema);
+  const kind = getSchemaKind(def);
+  if (!def || !kind) return {};
+
+  const primitive = mapPrimitiveKind(kind);
+  if (primitive) return primitive;
+
+  const lower = kind.toLowerCase();
+
+  if (lower.includes('object')) {
+    const shape = getObjectShape(def);
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+
+    for (const [key, child] of Object.entries(shape)) {
+      const unwrapped = unwrapOptionalForRequired(child);
+      properties[key] = buildIntrospectedFallbackJSONSchema(unwrapped.schema, seen);
+      if (!unwrapped.optional) required.push(key);
+    }
+
+    const out: JsonSchema = {
+      type: 'object',
+      properties,
+      additionalProperties: true,
+    };
+
+    if (required.length > 0) {
+      out.required = required;
+    }
+
+    return out;
+  }
+
+  if (lower.includes('array')) {
+    const itemSchema = pickSchemaObjectCandidate(def, ['element', 'items', 'innerType', 'type']) ?? {};
+    return {
+      type: 'array',
+      items: buildIntrospectedFallbackJSONSchema(itemSchema, seen),
+    };
+  }
+
+  if (lower.includes('record')) {
+    const valueType = (def as Record<string, any>).valueType ?? (def as Record<string, any>).valueSchema;
+    return {
+      type: 'object',
+      additionalProperties: valueType ? buildIntrospectedFallbackJSONSchema(valueType, seen) : true,
+    };
+  }
+
+  if (lower.includes('tuple')) {
+    const items = Array.isArray((def as Record<string, any>).items)
+      ? ((def as Record<string, any>).items as unknown[])
+      : [];
+    const prefixItems = items.map((item) => buildIntrospectedFallbackJSONSchema(item, seen));
+    return {
+      type: 'array',
+      prefixItems,
+      minItems: prefixItems.length,
+      maxItems: prefixItems.length,
+    };
+  }
+
+  if (lower.includes('union')) {
+    const options =
+      ((def as Record<string, any>).options as unknown[]) ?? ((def as Record<string, any>).schemas as unknown[]) ?? [];
+    if (!Array.isArray(options) || options.length === 0) return {};
+    return {
+      anyOf: options.map((option) => buildIntrospectedFallbackJSONSchema(option, seen)),
+    };
+  }
+
+  if (lower.includes('intersection')) {
+    const left = (def as Record<string, any>).left;
+    const right = (def as Record<string, any>).right;
+    if (!left || !right) return {};
+    return {
+      allOf: [buildIntrospectedFallbackJSONSchema(left, seen), buildIntrospectedFallbackJSONSchema(right, seen)],
+    };
+  }
+
+  if (lower.includes('enum')) {
+    const enumValues = extractEnumValues(def);
+    if (enumValues.length > 0) {
+      const allString = enumValues.every((v) => typeof v === 'string');
+      const allNumber = enumValues.every((v) => typeof v === 'number');
+      const allBoolean = enumValues.every((v) => typeof v === 'boolean');
+      if (allString) return { type: 'string', enum: enumValues };
+      if (allNumber) return { type: 'number', enum: enumValues };
+      if (allBoolean) return { type: 'boolean', enum: enumValues };
+      return { enum: enumValues };
+    }
+    return {};
+  }
+
+  if (lower.includes('picklist')) {
+    const enumValues = extractEnumValues(def);
+    if (enumValues.length > 0) {
+      const allString = enumValues.every((v) => typeof v === 'string');
+      if (allString) return { type: 'string', enum: enumValues };
+      return { enum: enumValues };
+    }
+    return {};
+  }
+
+  if (lower.includes('literal')) {
+    const value = (def as Record<string, any>).value;
+    if (value === undefined) return {};
+    const valueType = value === null ? 'null' : typeof value;
+    if (valueType === 'string' || valueType === 'number' || valueType === 'boolean' || valueType === 'null') {
+      return { type: valueType, const: value };
+    }
+    return { const: value };
+  }
+
+  if (lower.includes('nullable')) {
+    const inner = pickSchemaChild(def);
+    if (!inner) return {};
+    return {
+      anyOf: [buildIntrospectedFallbackJSONSchema(inner, seen), { type: 'null' }],
+    };
+  }
+
+  if (lower.includes('lazy')) {
+    const getter = (def as Record<string, any>).getter;
+    if (typeof getter !== 'function') return {};
+    try {
+      return buildIntrospectedFallbackJSONSchema(getter(), seen);
+    } catch {
+      return {};
+    }
+  }
+
+  const child = pickSchemaChild(def);
+  if (child) return buildIntrospectedFallbackJSONSchema(child, seen);
+
+  return {};
+}
+
+function buildFallbackJSONSchema(schema: unknown): JsonSchema {
+  const def = getValidatorSchemaDef(schema);
+  if (!def) return {};
+  return buildIntrospectedFallbackJSONSchema(schema);
+}
+
 function addStructuredInputToOperation(operation: Record<string, any>, inputJSONSchema: JsonSchema): void {
   if (!isRecord(inputJSONSchema)) return;
   if (inputJSONSchema.type !== 'object' || !isRecord(inputJSONSchema.properties)) {

package/src/start-vector.ts

@@ -0,0 +1,50 @@
+import { ConfigLoader } from './core/config-loader';
+import { DEFAULT_CONFIG } from './constants';
+import { getVectorInstance } from './core/vector';
+import type { DefaultVectorTypes, StartVectorOptions, StartedVectorApp, VectorTypes } from './types';
+
+export async function startVector<TTypes extends VectorTypes = DefaultVectorTypes>(
+  options: StartVectorOptions<TTypes> = {}
+): Promise<StartedVectorApp<TTypes>> {
+  const configLoader = new ConfigLoader<TTypes>(options.configPath);
+  const loadedConfig = await configLoader.load();
+  const configSource = configLoader.getConfigSource();
+
+  let config = { ...loadedConfig };
+  if (options.mutateConfig) {
+    config = await options.mutateConfig(config, { configSource });
+  }
+
+  if (options.config) {
+    config = { ...config, ...options.config };
+  }
+
+  if (options.autoDiscover !== undefined) {
+    config.autoDiscover = options.autoDiscover;
+  }
+
+  const vector = getVectorInstance<TTypes>();
+  const resolvedProtectedHandler =
+    options.protectedHandler !== undefined ? options.protectedHandler : await configLoader.loadAuthHandler();
+  const resolvedCacheHandler =
+    options.cacheHandler !== undefined ? options.cacheHandler : await configLoader.loadCacheHandler();
+
+  vector.setProtectedHandler(resolvedProtectedHandler ?? null);
+  vector.setCacheHandler(resolvedCacheHandler ?? null);
+
+  const server = await vector.startServer(config);
+  const effectiveConfig = {
+    ...config,
+    port: server.port ?? config.port ?? DEFAULT_CONFIG.PORT,
+    hostname: server.hostname || config.hostname || DEFAULT_CONFIG.HOSTNAME,
+    reusePort: config.reusePort !== false,
+    idleTimeout: config.idleTimeout ?? 60,
+  };
+
+  return {
+    server,
+    config: effectiveConfig,
+    stop: () => vector.stop(),
+    shutdown: () => vector.shutdown(),
+  };
+}

package/src/types/index.ts

@@ -1,4 +1,5 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from './standard-schema';
+import type { Server } from 'bun';
 
 // Default AuthUser type - users can override this with their own type
 export interface DefaultAuthUser {
@@ -150,6 +151,31 @@ export interface VectorConfig<TTypes extends VectorTypes = DefaultVectorTypes> {
   idleTimeout?: number;
   defaults?: VectorDefaults;
   openapi?: OpenAPIOptions | boolean;
+  startup?: StartupHandler;
+  shutdown?: ShutdownHandler;
+}
+
+export interface StartVectorContext {
+  configSource: 'user' | 'default';
+}
+
+export interface StartVectorOptions<TTypes extends VectorTypes = DefaultVectorTypes> {
+  configPath?: string;
+  config?: Partial<VectorConfig<TTypes>>;
+  autoDiscover?: boolean;
+  protectedHandler?: ProtectedHandler<TTypes> | null;
+  cacheHandler?: CacheHandler | null;
+  mutateConfig?: (
+    config: VectorConfig<TTypes>,
+    context: StartVectorContext
+  ) => VectorConfig<TTypes> | Promise<VectorConfig<TTypes>>;
+}
+
+export interface StartedVectorApp<TTypes extends VectorTypes = DefaultVectorTypes> {
+  server: Server;
+  config: VectorConfig<TTypes>;
+  stop: () => void;
+  shutdown: () => Promise<void>;
 }
 
 // New config-driven schema - flat structure
@@ -178,6 +204,10 @@ export interface VectorConfigSchema<TTypes extends VectorTypes = DefaultVectorTy
   // OpenAPI/docs configuration
   openapi?: OpenAPIOptions | boolean;
 
+  // Startup lifecycle
+  startup?: StartupHandler;
+  shutdown?: ShutdownHandler;
+
   // Custom types for TypeScript
   types?: VectorTypes;
 }
@@ -194,6 +224,7 @@ export interface CorsOptions {
 export interface OpenAPIDocsOptions {
   enabled?: boolean;
   path?: string;
+  exposePaths?: string[];
 }
 
 export interface OpenAPIInfoOptions {
@@ -220,6 +251,9 @@ export type AfterMiddlewareHandler<TTypes extends VectorTypes = DefaultVectorTyp
 ) => Promise<Response> | Response;
 export type MiddlewareHandler = BeforeMiddlewareHandler | AfterMiddlewareHandler;
 
+export type StartupHandler = () => Promise<void> | void;
+export type ShutdownHandler = () => Promise<void> | void;
+
 export type RouteHandler<TTypes extends VectorTypes = DefaultVectorTypes, TValidatedInput = undefined> = (
   request: VectorRequest<TTypes, TValidatedInput>
 ) => Promise<any> | any;

package/src/utils/logger.ts

@@ -17,7 +17,7 @@ export class Logger {
   constructor(config: Partial<LoggerConfig> = {}) {
     this.config = {
       level: config.level ?? LogLevel.INFO,
-      prefix: config.prefix ?? '[Vector]',
+      prefix: config.prefix ?? '[vector]',
       timestamp: config.timestamp ?? true,
     };
   }

package/src/utils/validation.ts

@@ -13,6 +13,8 @@ export function validateConfig(config: VectorConfig): VectorConfig {
     cors: config.cors ? validateCorsOptions(config.cors) : undefined,
     before: config.before || [],
     finally: config.finally || [],
+    startup: config.startup,
+    shutdown: config.shutdown,
   };
 
   return validatedConfig;