veryfront 0.1.215 → 0.1.217

package/src/src/extensions/interfaces/bundler.ts

@@ -0,0 +1,116 @@
+/**
+ * Contract interface for module bundlers.
+ *
+ * Default implementation: `@veryfront/ext-esbuild`
+ *
+ * @module extensions/interfaces/bundler
+ */
+
+/** Options passed to {@link Bundler.bundle}. */
+export interface BundleOptions {
+  /** Entry point file paths. */
+  entryPoints: string[];
+  /** Output directory. */
+  outdir: string;
+  /** Bundle format (`esm`, `cjs`, `iife`). */
+  format?: "esm" | "cjs" | "iife";
+  /** Target environment(s). */
+  target?: string | string[];
+  /** Enable minification. */
+  minify?: boolean;
+  /** Enable source maps. */
+  sourcemap?: boolean | "inline" | "external";
+  /** Enable code splitting. */
+  splitting?: boolean;
+  /** Additional plugins. */
+  plugins?: BundlerPlugin[];
+  /** Extra implementation-specific options. */
+  [key: string]: unknown;
+}
+
+/** A single output file produced by a bundle operation. */
+export interface BundleOutput {
+  /** Absolute path to the output file. */
+  path: string;
+  /** Raw byte content. */
+  contents: Uint8Array;
+}
+
+/** Result returned from {@link Bundler.bundle}. */
+export interface BundleResult {
+  /** Output files produced by the bundle. */
+  outputs: BundleOutput[];
+  /** Warnings emitted during bundling. */
+  warnings: string[];
+  /** Errors encountered during bundling. */
+  errors: string[];
+}
+
+/** Options passed to {@link Bundler.transform}. */
+export interface TransformOptions {
+  /** Source code to transform. */
+  code: string;
+  /** Loader hint (`ts`, `tsx`, `jsx`, `css`, etc.). */
+  loader?: string;
+  /** Output format. */
+  format?: "esm" | "cjs" | "iife";
+  /** Target environment(s). */
+  target?: string | string[];
+  /** Enable minification. */
+  minify?: boolean;
+  /** Enable source maps. */
+  sourcemap?: boolean | "inline" | "external";
+  /** Extra implementation-specific options. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link Bundler.transform}. */
+export interface TransformResult {
+  /** Transformed source code. */
+  code: string;
+  /** Source map, if requested. */
+  map?: string;
+  /** Warnings emitted during transformation. */
+  warnings: string[];
+}
+
+/** Build context exposed to bundler plugins. */
+export interface BundlerPluginBuild {
+  /** Register a resolver callback for the given filter. */
+  onResolve(
+    options: { filter: RegExp; namespace?: string },
+    callback: (
+      args: { path: string; namespace: string },
+    ) => { path?: string; namespace?: string; external?: boolean } | undefined,
+  ): void;
+  /** Register a loader callback for the given filter. */
+  onLoad(
+    options: { filter: RegExp; namespace?: string },
+    callback: (
+      args: { path: string; namespace: string },
+    ) => { contents?: string; loader?: string } | undefined,
+  ): void;
+}
+
+/** A bundler plugin that hooks into the build pipeline. */
+export interface BundlerPlugin {
+  /** Unique plugin name. */
+  name: string;
+  /** Called once when the plugin is registered. */
+  setup(build: BundlerPluginBuild): void;
+}
+
+/**
+ * Bundler contract interface.
+ *
+ * Implementations compile and bundle application source code into
+ * optimized output suitable for deployment or development.
+ */
+export interface Bundler {
+  /** Bundle one or more entry points into output files. */
+  bundle(options: BundleOptions): Promise<BundleResult>;
+  /** Transform a single source string without writing to disk. */
+  transform(options: TransformOptions): Promise<TransformResult>;
+  /** Release bundler resources (child processes, watchers, etc.). */
+  stop?(): Promise<void>;
+}

package/src/src/extensions/interfaces/cache-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Contract interface for key-value cache stores.
+ *
+ * Default implementation: `@veryfront/ext-redis`
+ *
+ * @module extensions/interfaces/cache-store
+ */
+
+/**
+ * CacheStore contract interface.
+ *
+ * Implementations provide key-value caching with optional TTL support.
+ */
+export interface CacheStore {
+  /** Retrieve a cached value by key. Returns `undefined` on miss. */
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  /** Store a value under the given key with an optional TTL in seconds. */
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+  /** Delete a cached entry. */
+  delete(key: string): Promise<void>;
+  /** Check whether a key exists in the cache. */
+  has(key: string): Promise<boolean>;
+  /** Remove all entries from the cache. */
+  clear(): Promise<void>;
+  /** Close connections and release resources. */
+  disconnect?(): Promise<void>;
+}

package/src/src/extensions/interfaces/code-parser.ts

@@ -0,0 +1,84 @@
+/**
+ * Contract interface for code parsing and AST manipulation.
+ *
+ * Default implementation: `@veryfront/ext-babel`
+ *
+ * @module extensions/interfaces/code-parser
+ */
+
+/** A single node in an abstract syntax tree. */
+export interface ASTNode {
+  /** Node type identifier (e.g. `"Identifier"`, `"CallExpression"`). */
+  type: string;
+  /** Start character offset in the source. */
+  start?: number;
+  /** End character offset in the source. */
+  end?: number;
+  /** Child nodes and properties. */
+  [key: string]: unknown;
+}
+
+/** Wrapper providing traversal context for a visited node. */
+export interface NodePath<T extends ASTNode = ASTNode> {
+  /** The AST node at this path. */
+  node: T;
+  /** The parent path, if any. */
+  parent: NodePath | undefined;
+  /** Replace this node with one or more new nodes. */
+  replaceWith(node: ASTNode): void;
+  /** Remove this node from the tree. */
+  remove(): void;
+}
+
+/** Visitor callbacks keyed by node type. */
+export interface TraverseVisitor {
+  [nodeType: string]:
+    | ((path: NodePath) => void)
+    | {
+      enter?(path: NodePath): void;
+      exit?(path: NodePath): void;
+    };
+}
+
+/** Options passed to {@link CodeParser.parse}. */
+export interface ParseOptions {
+  /** Source code to parse. */
+  code: string;
+  /** File path hint for parser configuration (e.g. `.tsx`). */
+  filePath?: string;
+  /** Additional parser-specific options. */
+  [key: string]: unknown;
+}
+
+/** Options passed to {@link CodeParser.generate}. */
+export interface GenerateOptions {
+  /** Include source maps in the output. */
+  sourceMaps?: boolean;
+  /** Minify the generated code. */
+  minified?: boolean;
+  /** Additional generator-specific options. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link CodeParser.generate}. */
+export interface GenerateResult {
+  /** Generated source code. */
+  code: string;
+  /** Source map, if requested. */
+  map?: string;
+}
+
+/**
+ * CodeParser contract interface.
+ *
+ * Implementations parse source code into ASTs, traverse/transform
+ * nodes, and generate code back from modified trees.
+ */
+export interface CodeParser {
+  /** Parse source code into an abstract syntax tree. */
+  parse(options: ParseOptions): Promise<ASTNode>;
+  /** Walk the AST calling visitor callbacks for matching node types. */
+  traverse(ast: ASTNode, visitor: TraverseVisitor): void;
+  /** Generate source code from an AST. */
+  generate(ast: ASTNode, options?: GenerateOptions): Promise<GenerateResult>;
+}

package/src/src/extensions/interfaces/content-transformer.ts

@@ -0,0 +1,38 @@
+/**
+ * Contract interface for content transformation pipelines.
+ *
+ * Default implementation: `@veryfront/ext-mdx`
+ *
+ * @module extensions/interfaces/content-transformer
+ */
+
+/** Options passed to {@link ContentTransformer.transform}. */
+export interface ContentTransformOptions {
+  /** Raw source content (e.g. MDX, Markdown). */
+  source: string;
+  /** File path hint for the source content. */
+  filePath?: string;
+  /** Additional remark/rehype plugins or processor-specific settings. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link ContentTransformer.transform}. */
+export interface ContentTransformResult {
+  /** Transformed output code. */
+  code: string;
+  /** Front-matter or metadata extracted from the source. */
+  frontmatter?: Record<string, unknown>;
+  /** Extracted table-of-contents headings. */
+  headings?: Array<{ depth: number; text: string; slug: string }>;
+}
+
+/**
+ * ContentTransformer contract interface.
+ *
+ * Implementations transform authoring formats (MDX, Markdown, etc.)
+ * into renderable code or HTML.
+ */
+export interface ContentTransformer {
+  /** Transform source content into its processed form. */
+  transform(options: ContentTransformOptions): Promise<ContentTransformResult>;
+}

package/src/src/extensions/interfaces/css-processor.ts

@@ -0,0 +1,40 @@
+/**
+ * Contract interface for CSS processing engines.
+ *
+ * Default implementation: `@veryfront/ext-tailwind`
+ *
+ * @module extensions/interfaces/css-processor
+ */
+
+/** Options passed to {@link CSSProcessor.process}. */
+export interface CSSProcessOptions {
+  /** Raw CSS or utility-class input. */
+  content: string;
+  /** Paths to source files used for scanning class usage. */
+  sources?: string[];
+  /** Enable minification of the output. */
+  minify?: boolean;
+  /** Extra implementation-specific options. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link CSSProcessor.process}. */
+export interface CSSProcessResult {
+  /** Processed CSS output. */
+  css: string;
+  /** Source map, if generated. */
+  map?: string;
+}
+
+/**
+ * CSSProcessor contract interface.
+ *
+ * Implementations compile utility classes or raw CSS into optimized
+ * stylesheets ready for the browser.
+ */
+export interface CSSProcessor {
+  /** Process CSS input and return the compiled result. */
+  process(options: CSSProcessOptions): Promise<CSSProcessResult>;
+  /** Merge class names using the processor's conflict-resolution strategy. */
+  mergeClasses?(...classes: string[]): string;
+}

package/src/src/extensions/interfaces/database-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Contract interface for database clients.
+ *
+ * Default implementation: `@veryfront/ext-postgres`
+ *
+ * @module extensions/interfaces/database-client
+ */
+
+/** Result returned from {@link DatabaseClient.query}. */
+export interface QueryResult<T = Record<string, unknown>> {
+  /** Array of rows returned by the query. */
+  rows: T[];
+  /** Number of rows affected by the statement. */
+  rowCount: number;
+}
+
+/**
+ * DatabaseClient contract interface.
+ *
+ * Implementations provide parameterized query execution against a
+ * relational or document database.
+ */
+export interface DatabaseClient {
+  /** Run a read query and return the matching rows. */
+  query<T = Record<string, unknown>>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<QueryResult<T>>;
+  /** Execute a write statement and return the affected row count. */
+  execute(sql: string, params?: unknown[]): Promise<QueryResult>;
+  /** Open or initialize the database connection. */
+  connect(): Promise<void>;
+  /** Close the database connection and release resources. */
+  disconnect(): Promise<void>;
+}

package/src/src/extensions/interfaces/embedding-provider.ts

@@ -0,0 +1,39 @@
+/**
+ * Contract interface for text embedding providers.
+ *
+ * Default implementation: `@veryfront/ext-embeddings`
+ *
+ * @module extensions/interfaces/embedding-provider
+ */
+
+/** Options passed to {@link EmbeddingProvider.embed}. */
+export interface EmbeddingOptions {
+  /** Model identifier (e.g. `"text-embedding-3-small"`). */
+  model: string;
+  /** Input texts to embed. */
+  input: string[];
+  /** Additional provider-specific options. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link EmbeddingProvider.embed}. */
+export interface EmbeddingResult {
+  /** One embedding vector per input string. */
+  embeddings: number[][];
+  /** Token usage statistics. */
+  usage?: {
+    promptTokens: number;
+    totalTokens: number;
+  };
+}
+
+/**
+ * EmbeddingProvider contract interface.
+ *
+ * Implementations convert text inputs into dense vector embeddings
+ * for similarity search and retrieval-augmented generation.
+ */
+export interface EmbeddingProvider {
+  /** Generate embedding vectors for the given input texts. */
+  embed(options: EmbeddingOptions): Promise<EmbeddingResult>;
+}

package/src/src/extensions/interfaces/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Barrel export for all extension contract interfaces.
+ *
+ * Every export is a pure TypeScript type -- no runtime code is emitted.
+ *
+ * @module extensions/interfaces
+ */
+
+// Bundler
+import "../../../_dnt.polyfills.js";
+
+export type {
+  BundleOptions,
+  BundleOutput,
+  Bundler,
+  BundleResult,
+  BundlerPlugin,
+  BundlerPluginBuild,
+  TransformOptions,
+  TransformResult,
+} from "./bundler.js";
+
+// Cache store
+export type { CacheStore } from "./cache-store.js";
+
+// CSS processor
+export type { CSSProcessOptions, CSSProcessor, CSSProcessResult } from "./css-processor.js";
+
+// Content transformer
+export type {
+  ContentTransformer,
+  ContentTransformOptions,
+  ContentTransformResult,
+} from "./content-transformer.js";
+
+// Database client
+export type { DatabaseClient, QueryResult } from "./database-client.js";
+
+// Auth provider
+export type { AuthProvider, SignOptions, TokenPayload, VerifyOptions } from "./auth-provider.js";
+
+// Tracing exporter
+export type { SpanData, TracingExporter } from "./tracing-exporter.js";
+
+// AI model provider
+export type {
+  AIModelProvider,
+  ChatMessage,
+  CompletionOptions,
+  CompletionResult,
+  ContentPart,
+  StreamChunk,
+  ToolDefinition,
+} from "./ai-model-provider.js";
+
+// Embedding provider
+export type { EmbeddingOptions, EmbeddingProvider, EmbeddingResult } from "./embedding-provider.js";
+
+// Code parser
+export type {
+  ASTNode,
+  CodeParser,
+  GenerateOptions,
+  GenerateResult,
+  NodePath,
+  ParseOptions,
+  TraverseVisitor,
+} from "./code-parser.js";
+
+// Schema validator
+export type {
+  Schema,
+  SchemaValidator,
+  ValidationFailure,
+  ValidationIssue,
+  ValidationResult,
+  ValidationSuccess,
+} from "./schema-validator.js";
+
+// Node compatibility
+export type { NodeCompat } from "./node-compat.js";

package/src/src/extensions/interfaces/node-compat.ts

@@ -0,0 +1,25 @@
+/**
+ * Contract interface for Node.js compatibility shims.
+ *
+ * Default implementation: `@veryfront/ext-node-compat`
+ *
+ * @module extensions/interfaces/node-compat
+ */
+
+/**
+ * NodeCompat contract interface.
+ *
+ * Implementations provide access to Node.js-compatible APIs in
+ * environments where native Node modules are unavailable (e.g. Deno).
+ *
+ * Each getter returns the module's namespace object, matching the
+ * shape of the corresponding Node.js built-in.
+ */
+export interface NodeCompat {
+  /** Return a Node-compatible `fs` module (sync + async + promises). */
+  getFS(): unknown;
+  /** Return a Node-compatible `path` module. */
+  getPath(): unknown;
+  /** Return a Node-compatible `WebSocket` constructor. */
+  getWebSocket(): unknown;
+}

package/src/src/extensions/interfaces/schema-validator.ts

@@ -0,0 +1,51 @@
+/**
+ * Contract interface for schema validation.
+ *
+ * Default implementation: `@veryfront/ext-zod`
+ *
+ * @module extensions/interfaces/schema-validator
+ */
+
+/** An opaque schema definition that validates and infers type `T`. */
+export interface Schema<T = unknown> {
+  /** Brand field for nominal typing -- not used at runtime. */
+  readonly _output: T;
+}
+
+/** A single validation issue with location context. */
+export interface ValidationIssue {
+  /** Dot-path to the offending field (e.g. `"user.email"`). */
+  path: (string | number)[];
+  /** Human-readable error message. */
+  message: string;
+  /** Machine-readable error code. */
+  code?: string;
+}
+
+/** Successful validation outcome. */
+export interface ValidationSuccess<T> {
+  success: true;
+  /** Parsed and validated data. */
+  data: T;
+}
+
+/** Failed validation outcome. */
+export interface ValidationFailure {
+  success: false;
+  /** List of issues found during validation. */
+  issues: ValidationIssue[];
+}
+
+/** Discriminated union of validation outcomes. */
+export type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+
+/**
+ * SchemaValidator contract interface.
+ *
+ * Implementations validate unknown input against a typed schema and
+ * return a discriminated success/failure result.
+ */
+export interface SchemaValidator {
+  /** Validate `data` against the given schema. */
+  validate<T>(schema: Schema<T>, data: unknown): ValidationResult<T>;
+}

package/src/src/extensions/interfaces/tracing-exporter.ts

@@ -0,0 +1,42 @@
+/**
+ * Contract interface for tracing/telemetry exporters.
+ *
+ * Default implementation: `@veryfront/ext-opentelemetry`
+ *
+ * @module extensions/interfaces/tracing-exporter
+ */
+
+/** Data describing a single trace span. */
+export interface SpanData {
+  /** Unique span identifier. */
+  spanId: string;
+  /** Trace identifier this span belongs to. */
+  traceId: string;
+  /** Parent span identifier, if any. */
+  parentSpanId?: string;
+  /** Human-readable operation name. */
+  name: string;
+  /** Span kind (`client`, `server`, `internal`, `producer`, `consumer`). */
+  kind: "client" | "server" | "internal" | "producer" | "consumer";
+  /** Start time as a Unix timestamp in milliseconds. */
+  startTime: number;
+  /** End time as a Unix timestamp in milliseconds. */
+  endTime: number;
+  /** Key-value attributes attached to the span. */
+  attributes: Record<string, string | number | boolean>;
+  /** Status of the span. */
+  status: { code: "ok" | "error" | "unset"; message?: string };
+}
+
+/**
+ * TracingExporter contract interface.
+ *
+ * Implementations export collected trace spans to an observability
+ * backend (e.g. Jaeger, Zipkin, OTLP collector).
+ */
+export interface TracingExporter {
+  /** Export a batch of completed spans. */
+  export(spans: SpanData[]): Promise<void>;
+  /** Flush pending data and release resources. */
+  shutdown(): Promise<void>;
+}