@objectstack/spec 0.1.2 → 0.3.0

package/dist/ai/rag-pipeline.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-pipeline.zod.d.ts","sourceRoot":"","sources":["../../src/ai/rag-pipeline.zod.ts"],"names":[],"mappings":"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"}

package/dist/ai/rag-pipeline.zod.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAGPipelineStatusSchema = exports.RAGQueryResponseSchema = exports.RAGQueryRequestSchema = exports.RAGPipelineConfigSchema = exports.DocumentLoaderConfigSchema = exports.VectorStoreConfigSchema = exports.RerankingConfigSchema = exports.RetrievalStrategySchema = exports.DocumentChunkSchema = exports.DocumentMetadataSchema = exports.ChunkingStrategySchema = exports.EmbeddingModelSchema = exports.VectorStoreProviderSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * RAG (Retrieval-Augmented Generation) Pipeline Protocol
+ *
+ * Defines schemas for building context-aware AI assistants using RAG techniques.
+ * Enables vector search, document chunking, embeddings, and retrieval configuration.
+ */
+/**
+ * Vector Store Provider
+ */
+exports.VectorStoreProviderSchema = zod_1.z.enum([
+    'pinecone',
+    'weaviate',
+    'qdrant',
+    'milvus',
+    'chroma',
+    'pgvector',
+    'redis',
+    'opensearch',
+    'elasticsearch',
+    'custom',
+]);
+/**
+ * Embedding Model
+ */
+exports.EmbeddingModelSchema = zod_1.z.object({
+    provider: zod_1.z.enum(['openai', 'cohere', 'huggingface', 'azure_openai', 'local', 'custom']),
+    model: zod_1.z.string().describe('Model name (e.g., "text-embedding-3-large")'),
+    dimensions: zod_1.z.number().int().positive().describe('Embedding vector dimensions'),
+    maxTokens: zod_1.z.number().int().positive().optional().describe('Maximum tokens per embedding'),
+    batchSize: zod_1.z.number().int().positive().optional().default(100).describe('Batch size for embedding'),
+    endpoint: zod_1.z.string().url().optional().describe('Custom endpoint URL'),
+    apiKey: zod_1.z.string().optional().describe('API key or reference to secret'),
+});
+/**
+ * Text Chunking Strategy
+ */
+exports.ChunkingStrategySchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({
+        type: zod_1.z.literal('fixed'),
+        chunkSize: zod_1.z.number().int().positive().describe('Fixed chunk size in tokens/chars'),
+        chunkOverlap: zod_1.z.number().int().min(0).default(0).describe('Overlap between chunks'),
+        unit: zod_1.z.enum(['tokens', 'characters']).default('tokens'),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('semantic'),
+        model: zod_1.z.string().optional().describe('Model for semantic chunking'),
+        minChunkSize: zod_1.z.number().int().positive().default(100),
+        maxChunkSize: zod_1.z.number().int().positive().default(1000),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('recursive'),
+        separators: zod_1.z.array(zod_1.z.string()).default(['\n\n', '\n', ' ', '']),
+        chunkSize: zod_1.z.number().int().positive(),
+        chunkOverlap: zod_1.z.number().int().min(0).default(0),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('markdown'),
+        maxChunkSize: zod_1.z.number().int().positive().default(1000),
+        respectHeaders: zod_1.z.boolean().default(true).describe('Keep headers with content'),
+        respectCodeBlocks: zod_1.z.boolean().default(true).describe('Keep code blocks intact'),
+    }),
+]);
+/**
+ * Document Metadata Schema
+ */
+exports.DocumentMetadataSchema = zod_1.z.object({
+    source: zod_1.z.string().describe('Document source (file path, URL, etc.)'),
+    sourceType: zod_1.z.enum(['file', 'url', 'api', 'database', 'custom']).optional(),
+    title: zod_1.z.string().optional(),
+    author: zod_1.z.string().optional(),
+    createdAt: zod_1.z.string().optional().describe('ISO timestamp'),
+    updatedAt: zod_1.z.string().optional().describe('ISO timestamp'),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+    category: zod_1.z.string().optional(),
+    language: zod_1.z.string().optional().describe('Document language (ISO 639-1 code)'),
+    custom: zod_1.z.record(zod_1.z.any()).optional().describe('Custom metadata fields'),
+});
+/**
+ * Document Chunk
+ */
+exports.DocumentChunkSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Unique chunk identifier'),
+    content: zod_1.z.string().describe('Chunk text content'),
+    embedding: zod_1.z.array(zod_1.z.number()).optional().describe('Embedding vector'),
+    metadata: exports.DocumentMetadataSchema,
+    chunkIndex: zod_1.z.number().int().min(0).describe('Chunk position in document'),
+    tokens: zod_1.z.number().int().optional().describe('Token count'),
+});
+/**
+ * Retrieval Strategy
+ */
+exports.RetrievalStrategySchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({
+        type: zod_1.z.literal('similarity'),
+        topK: zod_1.z.number().int().positive().default(5).describe('Number of results to retrieve'),
+        scoreThreshold: zod_1.z.number().min(0).max(1).optional().describe('Minimum similarity score'),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('mmr'),
+        topK: zod_1.z.number().int().positive().default(5),
+        fetchK: zod_1.z.number().int().positive().default(20).describe('Initial fetch size'),
+        lambda: zod_1.z.number().min(0).max(1).default(0.5).describe('Diversity vs relevance (0=diverse, 1=relevant)'),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('hybrid'),
+        topK: zod_1.z.number().int().positive().default(5),
+        vectorWeight: zod_1.z.number().min(0).max(1).default(0.7).describe('Weight for vector search'),
+        keywordWeight: zod_1.z.number().min(0).max(1).default(0.3).describe('Weight for keyword search'),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('parent_document'),
+        topK: zod_1.z.number().int().positive().default(5),
+        retrieveParent: zod_1.z.boolean().default(true).describe('Retrieve full parent document'),
+    }),
+]);
+/**
+ * Reranking Configuration
+ */
+exports.RerankingConfigSchema = zod_1.z.object({
+    enabled: zod_1.z.boolean().default(false),
+    model: zod_1.z.string().optional().describe('Reranking model name'),
+    provider: zod_1.z.enum(['cohere', 'huggingface', 'custom']).optional(),
+    topK: zod_1.z.number().int().positive().default(3).describe('Final number of results after reranking'),
+});
+/**
+ * Vector Store Configuration
+ */
+exports.VectorStoreConfigSchema = zod_1.z.object({
+    provider: exports.VectorStoreProviderSchema,
+    indexName: zod_1.z.string().describe('Index/collection name'),
+    namespace: zod_1.z.string().optional().describe('Namespace for multi-tenancy'),
+    /** Connection */
+    host: zod_1.z.string().optional().describe('Vector store host'),
+    port: zod_1.z.number().int().optional().describe('Vector store port'),
+    apiKey: zod_1.z.string().optional().describe('API key or reference to secret'),
+    /** Configuration */
+    dimensions: zod_1.z.number().int().positive().describe('Vector dimensions'),
+    metric: zod_1.z.enum(['cosine', 'euclidean', 'dotproduct']).optional().default('cosine'),
+    /** Performance */
+    batchSize: zod_1.z.number().int().positive().optional().default(100),
+    connectionPoolSize: zod_1.z.number().int().positive().optional().default(10),
+    timeout: zod_1.z.number().int().positive().optional().default(30000).describe('Timeout in milliseconds'),
+});
+/**
+ * Document Loader Configuration
+ */
+exports.DocumentLoaderConfigSchema = zod_1.z.object({
+    type: zod_1.z.enum(['file', 'directory', 'url', 'api', 'database', 'custom']),
+    /** Source */
+    source: zod_1.z.string().describe('Source path, URL, or identifier'),
+    /** File Types */
+    fileTypes: zod_1.z.array(zod_1.z.string()).optional().describe('Accepted file extensions (e.g., [".pdf", ".md"])'),
+    /** Processing */
+    recursive: zod_1.z.boolean().optional().default(false).describe('Process directories recursively'),
+    maxFileSize: zod_1.z.number().int().optional().describe('Maximum file size in bytes'),
+    excludePatterns: zod_1.z.array(zod_1.z.string()).optional().describe('Patterns to exclude'),
+    /** Text Extraction */
+    extractImages: zod_1.z.boolean().optional().default(false).describe('Extract text from images (OCR)'),
+    extractTables: zod_1.z.boolean().optional().default(false).describe('Extract and format tables'),
+    /** Custom Loader */
+    loaderConfig: zod_1.z.record(zod_1.z.any()).optional().describe('Custom loader-specific config'),
+});
+/**
+ * RAG Pipeline Configuration
+ */
+exports.RAGPipelineConfigSchema = zod_1.z.object({
+    /** Identity */
+    name: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Pipeline name (snake_case)'),
+    label: zod_1.z.string().describe('Display name'),
+    description: zod_1.z.string().optional(),
+    /** Components */
+    embedding: exports.EmbeddingModelSchema,
+    vectorStore: exports.VectorStoreConfigSchema,
+    chunking: exports.ChunkingStrategySchema,
+    retrieval: exports.RetrievalStrategySchema,
+    reranking: exports.RerankingConfigSchema.optional(),
+    /** Document Loading */
+    loaders: zod_1.z.array(exports.DocumentLoaderConfigSchema).optional().describe('Document loaders'),
+    /** Context Management */
+    maxContextTokens: zod_1.z.number().int().positive().default(4000).describe('Maximum tokens in context'),
+    contextWindow: zod_1.z.number().int().positive().optional().describe('LLM context window size'),
+    /** Metadata Filtering */
+    metadataFilters: zod_1.z.record(zod_1.z.union([
+        zod_1.z.string(),
+        zod_1.z.number(),
+        zod_1.z.boolean(),
+        zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number()])),
+    ])).optional().describe('Filters for retrieval (e.g., {category: "docs", status: "published"})'),
+    /** Caching */
+    enableCache: zod_1.z.boolean().default(true),
+    cacheTTL: zod_1.z.number().int().positive().default(3600).describe('Cache TTL in seconds'),
+    cacheInvalidationStrategy: zod_1.z.enum(['time_based', 'manual', 'on_update']).default('time_based').optional(),
+});
+/**
+ * RAG Query Request
+ */
+exports.RAGQueryRequestSchema = zod_1.z.object({
+    query: zod_1.z.string().describe('User query'),
+    pipelineName: zod_1.z.string().describe('Pipeline to use'),
+    /** Override defaults */
+    topK: zod_1.z.number().int().positive().optional(),
+    metadataFilters: zod_1.z.record(zod_1.z.any()).optional(),
+    /** Context */
+    conversationHistory: zod_1.z.array(zod_1.z.object({
+        role: zod_1.z.enum(['user', 'assistant', 'system']),
+        content: zod_1.z.string(),
+    })).optional(),
+    /** Options */
+    includeMetadata: zod_1.z.boolean().default(true),
+    includeSources: zod_1.z.boolean().default(true),
+});
+/**
+ * RAG Query Response
+ */
+exports.RAGQueryResponseSchema = zod_1.z.object({
+    query: zod_1.z.string(),
+    results: zod_1.z.array(zod_1.z.object({
+        content: zod_1.z.string(),
+        score: zod_1.z.number(),
+        metadata: exports.DocumentMetadataSchema.optional(),
+        chunkId: zod_1.z.string().optional(),
+    })),
+    context: zod_1.z.string().describe('Assembled context for LLM'),
+    tokensUsed: zod_1.z.number().int().optional(),
+    retrievalTime: zod_1.z.number().optional().describe('Retrieval time in milliseconds'),
+});
+/**
+ * RAG Pipeline Status
+ */
+exports.RAGPipelineStatusSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    status: zod_1.z.enum(['active', 'indexing', 'error', 'disabled']),
+    documentsIndexed: zod_1.z.number().int().min(0),
+    lastIndexed: zod_1.z.string().optional().describe('ISO timestamp'),
+    errorMessage: zod_1.z.string().optional(),
+    health: zod_1.z.object({
+        vectorStore: zod_1.z.enum(['healthy', 'unhealthy', 'unknown']),
+        embeddingService: zod_1.z.enum(['healthy', 'unhealthy', 'unknown']),
+    }).optional(),
+});

package/dist/api/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * API Protocol Exports
+ *
+ * API Contracts & Envelopes
+ * - Request/Response schemas
+ * - Error handling
+ */
+export * from './contract.zod';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * API Protocol Exports
+ *
+ * API Contracts & Envelopes
+ * - Request/Response schemas
+ * - Error handling
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contract.zod"), exports);

package/dist/data/filter.zod.d.ts

@@ -0,0 +1,295 @@
+import { z } from 'zod';
+/**
+ * Unified Query DSL Specification
+ *
+ * Based on industry best practices from:
+ * - Prisma ORM
+ * - Strapi CMS
+ * - TypeORM
+ * - LoopBack Framework
+ *
+ * Version: 1.0.0
+ * Status: Draft
+ *
+ * Objective: Define a JSON-based, database-agnostic query syntax standard
+ * for data filtering interactions between frontend and backend APIs.
+ *
+ * Design Principles:
+ * 1. Declarative: Frontend describes "what data to get", not "how to query"
+ * 2. Database Agnostic: Syntax contains no database-specific directives
+ * 3. Type Safe: Structure can be statically inferred by TypeScript
+ * 4. Convention over Configuration: Implicit syntax for common queries
+ */
+/**
+ * Comparison operators for equality and inequality checks.
+ * Supported data types: Any
+ */
+export declare const EqualityOperatorSchema: z.ZodObject<{
+    /** Equal to (default) - SQL: = | MongoDB: $eq */
+    $eq: z.ZodOptional<z.ZodAny>;
+    /** Not equal to - SQL: <> or != | MongoDB: $ne */
+    $ne: z.ZodOptional<z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    $eq?: any;
+    $ne?: any;
+}, {
+    $eq?: any;
+    $ne?: any;
+}>;
+/**
+ * Comparison operators for numeric and date comparisons.
+ * Supported data types: Number, Date
+ */
+export declare const ComparisonOperatorSchema: z.ZodObject<{
+    /** Greater than - SQL: > | MongoDB: $gt */
+    $gt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Greater than or equal to - SQL: >= | MongoDB: $gte */
+    $gte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Less than - SQL: < | MongoDB: $lt */
+    $lt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    /** Less than or equal to - SQL: <= | MongoDB: $lte */
+    $lte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+}, "strip", z.ZodTypeAny, {
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+}, {
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+}>;
+/**
+ * Set operators for membership checks.
+ */
+export declare const SetOperatorSchema: z.ZodObject<{
+    /** In list - SQL: IN (?, ?, ?) | MongoDB: $in */
+    $in: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    /** Not in list - SQL: NOT IN (...) | MongoDB: $nin */
+    $nin: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, "strip", z.ZodTypeAny, {
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+}, {
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+}>;
+/**
+ * Range operator for interval checks (closed interval).
+ * SQL: BETWEEN ? AND ? | MongoDB: $gte AND $lte
+ */
+export declare const RangeOperatorSchema: z.ZodObject<{
+    /** Between (inclusive) - takes [min, max] array */
+    $between: z.ZodOptional<z.ZodTuple<[z.ZodUnion<[z.ZodNumber, z.ZodDate]>, z.ZodUnion<[z.ZodNumber, z.ZodDate]>], null>>;
+}, "strip", z.ZodTypeAny, {
+    $between?: [number | Date, number | Date] | undefined;
+}, {
+    $between?: [number | Date, number | Date] | undefined;
+}>;
+/**
+ * String pattern matching operators.
+ * Note: Case sensitivity should be handled at backend level.
+ */
+export declare const StringOperatorSchema: z.ZodObject<{
+    /** Contains substring - SQL: LIKE %?% | MongoDB: $regex */
+    $contains: z.ZodOptional<z.ZodString>;
+    /** Starts with prefix - SQL: LIKE ?% | MongoDB: $regex */
+    $startsWith: z.ZodOptional<z.ZodString>;
+    /** Ends with suffix - SQL: LIKE %? | MongoDB: $regex */
+    $endsWith: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+}, {
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+}>;
+/**
+ * Special check operators for null and existence.
+ */
+export declare const SpecialOperatorSchema: z.ZodObject<{
+    /** Is null check - SQL: IS NULL (true) / IS NOT NULL (false) | MongoDB: field: null */
+    $null: z.ZodOptional<z.ZodBoolean>;
+    /** Field exists check (primarily for NoSQL) - MongoDB: $exists */
+    $exist: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}, {
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}>;
+/**
+ * All field-level operators combined.
+ * These can be applied to individual fields in a filter.
+ */
+export declare const FieldOperatorsSchema: z.ZodObject<{
+    $eq: z.ZodOptional<z.ZodAny>;
+    $ne: z.ZodOptional<z.ZodAny>;
+    $gt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $gte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $lt: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $lte: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodDate]>>;
+    $in: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    $nin: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    $between: z.ZodOptional<z.ZodTuple<[z.ZodUnion<[z.ZodNumber, z.ZodDate]>, z.ZodUnion<[z.ZodNumber, z.ZodDate]>], null>>;
+    $contains: z.ZodOptional<z.ZodString>;
+    $startsWith: z.ZodOptional<z.ZodString>;
+    $endsWith: z.ZodOptional<z.ZodString>;
+    $null: z.ZodOptional<z.ZodBoolean>;
+    $exist: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    $eq?: any;
+    $ne?: any;
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+    $between?: [number | Date, number | Date] | undefined;
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}, {
+    $eq?: any;
+    $ne?: any;
+    $gt?: number | Date | undefined;
+    $gte?: number | Date | undefined;
+    $lt?: number | Date | undefined;
+    $lte?: number | Date | undefined;
+    $in?: any[] | undefined;
+    $nin?: any[] | undefined;
+    $between?: [number | Date, number | Date] | undefined;
+    $contains?: string | undefined;
+    $startsWith?: string | undefined;
+    $endsWith?: string | undefined;
+    $null?: boolean | undefined;
+    $exist?: boolean | undefined;
+}>;
+/**
+ * Recursive filter type that supports:
+ * 1. Implicit equality: { field: value }
+ * 2. Explicit operators: { field: { $op: value } }
+ * 3. Logical combinations: { $and: [...], $or: [...], $not: {...} }
+ * 4. Nested relations: { relation: { field: value } }
+ */
+export type FilterCondition = {
+    [key: string]: any | z.infer<typeof FieldOperatorsSchema> | FilterCondition;
+} & {
+    /** Logical AND - combines all conditions that must be true */
+    $and?: FilterCondition[];
+    /** Logical OR - at least one condition must be true */
+    $or?: FilterCondition[];
+    /** Logical NOT - negates the condition */
+    $not?: FilterCondition;
+};
+/**
+ * Zod schema for recursive filter validation.
+ * Uses z.lazy() to handle recursive structure.
+ */
+export declare const FilterConditionSchema: z.ZodType<FilterCondition>;
+/**
+ * Top-level query filter wrapper.
+ * This is typically used as the "where" clause in a query.
+ *
+ * @example
+ * ```typescript
+ * const filter: QueryFilter = {
+ *   where: {
+ *     status: "active",                    // Implicit equality
+ *     age: { $gte: 18 },                   // Explicit operator
+ *     $or: [                               // Logical combination
+ *       { role: "admin" },
+ *       { email: { $contains: "@company.com" } }
+ *     ],
+ *     profile: {                           // Nested relation
+ *       verified: true
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare const QueryFilterSchema: z.ZodObject<{
+    where: z.ZodOptional<z.ZodType<FilterCondition, z.ZodTypeDef, FilterCondition>>;
+}, "strip", z.ZodTypeAny, {
+    where?: FilterCondition | undefined;
+}, {
+    where?: FilterCondition | undefined;
+}>;
+/**
+ * Type-safe filter operators for use in TypeScript.
+ *
+ * @example
+ * ```typescript
+ * type UserFilter = Filter<User>;
+ *
+ * const filter: UserFilter = {
+ *   age: { $gte: 18 },
+ *   email: { $contains: "@example.com" }
+ * };
+ * ```
+ */
+export type Filter<T = any> = {
+    [K in keyof T]?: T[K] | {
+        $eq?: T[K];
+        $ne?: T[K];
+        $gt?: T[K] extends number | Date ? T[K] : never;
+        $gte?: T[K] extends number | Date ? T[K] : never;
+        $lt?: T[K] extends number | Date ? T[K] : never;
+        $lte?: T[K] extends number | Date ? T[K] : never;
+        $in?: T[K][];
+        $nin?: T[K][];
+        $between?: T[K] extends number | Date ? [T[K], T[K]] : never;
+        $contains?: T[K] extends string ? string : never;
+        $startsWith?: T[K] extends string ? string : never;
+        $endsWith?: T[K] extends string ? string : never;
+        $null?: boolean;
+        $exist?: boolean;
+    } | (T[K] extends object ? Filter<T[K]> : never);
+} & {
+    $and?: Filter<T>[];
+    $or?: Filter<T>[];
+    $not?: Filter<T>;
+};
+/**
+ * Scalar types supported by the filter system.
+ */
+export type Scalar = string | number | boolean | Date | null;
+export type FieldOperators = z.infer<typeof FieldOperatorsSchema>;
+export type QueryFilter = z.infer<typeof QueryFilterSchema>;
+/**
+ * Normalized filter AST structure.
+ * This is the internal representation after converting all syntactic sugar
+ * to explicit operators.
+ *
+ * Stage 1: Normalization Pass
+ * Input:  { age: 18, role: "admin" }
+ * Output: { $and: [{ age: { $eq: 18 } }, { role: { $eq: "admin" } }] }
+ *
+ * This simplifies adapter implementation by providing a consistent structure.
+ */
+export declare const NormalizedFilterSchema: z.ZodType<any>;
+export type NormalizedFilter = z.infer<typeof NormalizedFilterSchema>;
+/**
+ * All supported operator keys.
+ * Useful for validation and parsing.
+ */
+export declare const FILTER_OPERATORS: readonly ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$between", "$contains", "$startsWith", "$endsWith", "$null", "$exist"];
+/**
+ * Logical operator keys.
+ */
+export declare const LOGICAL_OPERATORS: readonly ["$and", "$or", "$not"];
+/**
+ * All operator keys (field + logical).
+ */
+export declare const ALL_OPERATORS: readonly ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte", "$in", "$nin", "$between", "$contains", "$startsWith", "$endsWith", "$null", "$exist", "$and", "$or", "$not"];
+export type FilterOperatorKey = typeof FILTER_OPERATORS[number];
+export type LogicalOperatorKey = typeof LOGICAL_OPERATORS[number];
+export type OperatorKey = typeof ALL_OPERATORS[number];
+//# sourceMappingURL=filter.zod.d.ts.map

package/dist/data/filter.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.zod.d.ts","sourceRoot":"","sources":["../../src/data/filter.zod.ts"],"names":[],"mappings":"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"}