semantic-primitives 0.1.0

package/dist/types/form-data/form-data.d.ts

@@ -0,0 +1,277 @@
+/**
+ * SemanticFormData - LLM-enhanced FormData type with semantic understanding
+ *
+ * Extends the native FormData with semantic operations including:
+ * - Intelligent field validation and matching
+ * - Form purpose detection
+ * - Sensitive data detection
+ * - Missing field suggestions
+ * - File validation
+ *
+ * Implements shared interfaces:
+ * - Semantic<FormData> - Base semantic wrapper
+ * - Comparable<FormData> - Semantic equality comparison
+ * - Explainable - Human-readable explanations
+ */
+import type { LLMConfig, Message } from '../../llm/types.ts';
+/** Type alias for FormData entry values (string or File) */
+type FormDataEntryValue = string | File;
+import type { SemanticEqualsResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, Explainable } from '../../shared/interfaces.ts';
+/** Extended semantic equals result with field mappings */
+export interface FormDataSemanticEqualsResult extends SemanticEqualsResult {
+    fieldMappings?: Record<string, string>;
+}
+/** Validation result with field-specific issues */
+export interface FormDataValidateResult {
+    valid: boolean;
+    issues: {
+        field: string;
+        issue: string;
+    }[];
+}
+/** Result of semantic field access */
+export interface FormDataSemanticGetResult {
+    value: FormDataEntryValue | null;
+    matchedField: string | undefined;
+    confidence: number;
+}
+/** Result of purpose inference */
+export interface FormDataInferPurposeResult {
+    purpose: string;
+    requiredFields: string[];
+    confidence: number;
+}
+/** Result of sensitive data detection */
+export interface FormDataDetectSensitiveResult {
+    hasSensitive: boolean;
+    fields: string[];
+    recommendation: string;
+}
+/** Suggestion for a missing field */
+export interface FormDataMissingSuggestion {
+    field: string;
+    reason: string;
+    required: boolean;
+}
+/** File validation rules */
+export interface FileValidationRules {
+    maxSize?: string;
+    allowedTypes?: string[];
+}
+/** File validation result */
+export interface FormDataFileValidateResult {
+    valid: boolean;
+    issues: {
+        field: string;
+        issue: string;
+    }[];
+}
+/** LLM client interface for dependency injection */
+export interface FormDataLLMClientInterface {
+    chat(options: {
+        messages: Message[];
+        systemPrompt?: string;
+    } & LLMConfig): Promise<{
+        content: string;
+    }>;
+}
+/**
+ * SemanticFormData class
+ * Wraps FormData with LLM-powered semantic operations
+ *
+ * Implements:
+ * - Semantic<FormData> - valueOf() returns the FormData value
+ * - Comparable<FormData> - semanticallyEquals() for comparison
+ * - Explainable - explain() for human-readable explanations
+ */
+export declare class SemanticFormData implements Semantic<FormData>, Comparable<FormData, FormDataSemanticEqualsResult>, Explainable {
+    private readonly _formData;
+    private readonly _context?;
+    private readonly _llmClient;
+    private readonly _llmConfig?;
+    /**
+     * Create a SemanticFormData instance
+     * @param formData - The FormData value to wrap
+     * @param context - Optional context about the form's purpose
+     * @param llmClient - Optional LLM client for dependency injection (useful for testing)
+     * @param llmConfig - Optional LLM configuration
+     */
+    constructor(formData: FormData, context?: string, llmClient?: FormDataLLMClientInterface, llmConfig?: LLMConfig);
+    /**
+     * Create SemanticFormData from existing FormData or object.
+     *
+     * @param data - FormData or plain object
+     * @param context - Context about the form's purpose
+     * @param llmClient - Optional LLM client for dependency injection
+     * @param llmConfig - Optional LLM configuration
+     * @returns SemanticFormData instance
+     *
+     * @example
+     * SemanticFormData.from({ name: "John", email: "john@example.com" })
+     * SemanticFormData.from(existingFormData, "user registration")
+     */
+    static from(data: FormData | Record<string, unknown>, context?: string, llmClient?: FormDataLLMClientInterface, llmConfig?: LLMConfig): SemanticFormData;
+    /**
+     * Get a string representation of all form fields for LLM prompts
+     */
+    private _getFieldsString;
+    /**
+     * Get file information for validation
+     */
+    private _getFilesString;
+    /**
+     * Check if two FormData objects are semantically equivalent.
+     *
+     * @param other - FormData to compare
+     * @param _options - Optional comparison options (unused, for interface compatibility)
+     * @returns Equivalence result with field mappings
+     *
+     * @example
+     * form1.semanticallyEquals(form2)
+     * // { equivalent: true, fieldMappings: { "firstName": "first_name" }, confidence: 0.95 }
+     */
+    semanticallyEquals(other: FormData, _options?: Record<string, unknown>): Promise<FormDataSemanticEqualsResult>;
+    /**
+     * Validate form data against semantic rules.
+     *
+     * @param rules - Validation rules in natural language
+     * @returns Validation result with field-specific issues
+     *
+     * @example
+     * form.validate([
+     *   "email must be valid",
+     *   "password must be strong",
+     *   "file must be an image"
+     * ])
+     */
+    validate(rules: string[]): Promise<FormDataValidateResult>;
+    /**
+     * Get a field using semantic matching.
+     *
+     * @param query - Field name or semantic description
+     * @returns Field value with match confidence
+     *
+     * @example
+     * form.semanticGet("user's email address")
+     * // { value: "john@example.com", matchedField: "email", confidence: 0.95 }
+     */
+    semanticGet(query: string): Promise<FormDataSemanticGetResult>;
+    /**
+     * Detect the purpose of this form.
+     *
+     * @returns Form purpose detection result
+     *
+     * @example
+     * form.inferPurpose()
+     * // { purpose: "user-registration", requiredFields: ["email", "password"], confidence: 0.92 }
+     */
+    inferPurpose(): Promise<FormDataInferPurposeResult>;
+    /**
+     * Check for sensitive data in the form.
+     *
+     * @returns Sensitivity analysis result
+     *
+     * @example
+     * form.detectSensitive()
+     * // { hasSensitive: true, fields: ["password", "ssn"], recommendation: "Use HTTPS" }
+     */
+    detectSensitive(): Promise<FormDataDetectSensitiveResult>;
+    /**
+     * Suggest missing fields based on form purpose.
+     *
+     * @returns Suggested fields with reasons
+     *
+     * @example
+     * form.suggestMissingFields()
+     * // [{ field: "confirmPassword", reason: "Registration forms typically require password confirmation", required: true }]
+     */
+    suggestMissingFields(): Promise<FormDataMissingSuggestion[]>;
+    /**
+     * Validate file fields in the form.
+     *
+     * @param rules - File validation rules
+     * @returns Validation result for file fields
+     *
+     * @example
+     * form.validateFiles({
+     *   maxSize: "5MB",
+     *   allowedTypes: ["image/*", "application/pdf"]
+     * })
+     */
+    validateFiles(rules: FileValidationRules): Promise<FormDataFileValidateResult>;
+    /**
+     * Explain the form contents.
+     *
+     * @param _context - Optional context (unused, for interface compatibility)
+     * @returns Human-readable explanation
+     *
+     * @example
+     * form.explain()
+     * // "User registration form with name, email, password, and profile picture"
+     */
+    explain(_context?: string): Promise<string>;
+    /**
+     * Convert to a plain object with semantic field names.
+     *
+     * @param targetConvention - Naming convention for keys (defaults to camelCase)
+     * @returns Plain object with converted field names
+     */
+    toObject(targetConvention?: 'camelCase' | 'snake_case'): Promise<Record<string, unknown>>;
+    /**
+     * Get the raw FormData value
+     * @returns The underlying FormData
+     */
+    valueOf(): FormData;
+    /**
+     * Get the context string
+     * @returns The context or undefined
+     */
+    getContext(): string | undefined;
+    /**
+     * Append a value to the form data
+     */
+    append(name: string, value: string | Blob, filename?: string): void;
+    /**
+     * Delete all values for a field
+     */
+    delete(name: string): void;
+    /**
+     * Get the first value for a field
+     */
+    get(name: string): FormDataEntryValue | null;
+    /**
+     * Get all values for a field
+     */
+    getAll(name: string): FormDataEntryValue[];
+    /**
+     * Check if a field exists
+     */
+    has(name: string): boolean;
+    /**
+     * Set a value for a field (replaces existing)
+     */
+    set(name: string, value: string | Blob, filename?: string): void;
+    /**
+     * Iterate over all entries
+     */
+    entries(): IterableIterator<[string, FormDataEntryValue]>;
+    /**
+     * Iterate over all keys
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Iterate over all values
+     */
+    values(): IterableIterator<FormDataEntryValue>;
+    /**
+     * forEach iteration
+     */
+    forEach(callback: (value: FormDataEntryValue, key: string, parent: FormData) => void): void;
+    /**
+     * Get all field names
+     */
+    getFieldNames(): string[];
+}
+export {};
+//# sourceMappingURL=form-data.d.ts.map

package/dist/types/form-data/form-data.d.ts.map

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

package/dist/types/form-data/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SemanticFormData Module
+ * LLM-enhanced FormData type with semantic understanding
+ */
+export { SemanticFormData, type FormDataSemanticEqualsResult, type FormDataValidateResult, type FormDataSemanticGetResult, type FormDataInferPurposeResult, type FormDataDetectSensitiveResult, type FormDataMissingSuggestion, type FileValidationRules, type FormDataFileValidateResult, type FormDataLLMClientInterface, } from './form-data.ts';
+export type { SemanticEqualsResult } from '../../shared/types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/form-data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/form-data/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,GAChC,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/form-data/prompts.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Prompts for SemanticFormData LLM operations
+ * These prompts are used for various semantic form data operations that require LLM understanding
+ */
+/**
+ * System prompt for semantic form data equality comparison
+ */
+export declare const SEMANTIC_EQUALS_SYSTEM = "You are a form data comparison assistant. Your task is to determine if two sets of form data are semantically equivalent.\n\nConsider these factors when comparing:\n- Field name variations (e.g., \"firstName\" vs \"first_name\" vs \"first-name\")\n- Similar field meanings (e.g., \"email\" vs \"emailAddress\" vs \"user_email\")\n- Value equivalence (same data, different formatting)\n- Missing fields that may have default values\n- Field ordering (typically irrelevant)\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for semantic form data equality
+ */
+export declare function semanticEqualsPrompt(fields1: string, fields2: string, context?: string): string;
+/**
+ * System prompt for form validation
+ */
+export declare const VALIDATE_SYSTEM = "You are a form validation assistant. Your task is to validate form data against semantic rules described in natural language.\n\nConsider:\n- Field value formats (email, phone, date patterns)\n- Required field presence\n- Value constraints (length, range, allowed values)\n- Cross-field validations (password confirmation, date ranges)\n- Business logic rules\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for form validation
+ */
+export declare function validatePrompt(fields: string, rules: string[]): string;
+/**
+ * System prompt for semantic field access
+ */
+export declare const SEMANTIC_GET_SYSTEM = "You are a form field matching assistant. Your task is to find form fields that match a semantic query.\n\nConsider:\n- Field name variations and conventions\n- Common abbreviations (e.g., \"addr\" for \"address\", \"tel\" for \"telephone\")\n- Semantic meaning beyond exact name matching\n- Context clues from other fields\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for semantic field access
+ */
+export declare function semanticGetPrompt(fields: string, query: string): string;
+/**
+ * System prompt for inferring form purpose
+ */
+export declare const INFER_PURPOSE_SYSTEM = "You are a form analysis assistant. Your task is to determine the purpose of a form based on its fields.\n\nCommon form purposes include:\n- user-registration: Sign-up forms with email, password, name\n- login: Authentication with username/email and password\n- contact: Contact forms with message, email, name\n- checkout: Payment forms with address, card details\n- profile-update: Profile editing with personal information\n- search: Search forms with query fields\n- feedback: Forms collecting user opinions\n- newsletter-signup: Email subscription forms\n- booking: Reservation forms with dates, times\n- file-upload: Forms for uploading documents/media\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for purpose inference
+ */
+export declare function inferPurposePrompt(fields: string, context?: string): string;
+/**
+ * System prompt for detecting sensitive data
+ */
+export declare const DETECT_SENSITIVE_SYSTEM = "You are a data sensitivity analyst. Your task is to identify sensitive data in form fields.\n\nCategories of sensitive data:\n- Personally Identifiable Information (PII): name, email, phone, address\n- Financial: credit card, bank account, SSN\n- Authentication: password, PIN, security questions\n- Health: medical information, health conditions\n- Legal: government IDs, legal documents\n\nSecurity recommendations:\n- Use HTTPS for transmission\n- Encrypt at rest\n- Minimize data collection\n- Implement access controls\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for sensitive data detection
+ */
+export declare function detectSensitivePrompt(fields: string): string;
+/**
+ * System prompt for suggesting missing fields
+ */
+export declare const SUGGEST_MISSING_SYSTEM = "You are a form design assistant. Your task is to suggest missing fields based on the form's purpose and existing fields.\n\nConsider:\n- Common patterns for the form type\n- Required vs optional fields\n- User experience best practices\n- Data completeness requirements\n- Regulatory requirements (GDPR consent, terms acceptance)\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for missing field suggestions
+ */
+export declare function suggestMissingFieldsPrompt(fields: string, purpose?: string): string;
+/**
+ * System prompt for file validation
+ */
+export declare const VALIDATE_FILES_SYSTEM = "You are a file validation assistant. Your task is to validate file uploads in form data.\n\nConsider:\n- File size limits (parse human-readable sizes like \"5MB\", \"1GB\")\n- MIME type restrictions\n- File extension matching\n- Security concerns (executable files, scripts)\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for file validation
+ */
+export declare function validateFilesPrompt(files: string, rules: {
+    maxSize?: string;
+    allowedTypes?: string[];
+}): string;
+/**
+ * System prompt for form explanation
+ */
+export declare const EXPLAIN_SYSTEM = "You are a form description assistant. Your task is to explain what a form is for in human-readable terms.\n\nConsider:\n- The purpose of the form\n- What data it collects\n- Who might use it\n- Key fields and their purposes\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for form explanation
+ */
+export declare function explainPrompt(fields: string, context?: string): string;
+/**
+ * System prompt for converting field names
+ */
+export declare const TO_OBJECT_SYSTEM = "You are a naming convention assistant. Your task is to convert form field names to a target naming convention.\n\nNaming conventions:\n- camelCase: firstName, lastName, emailAddress\n- snake_case: first_name, last_name, email_address\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for field name conversion
+ */
+export declare function toObjectPrompt(fields: string, targetConvention: 'camelCase' | 'snake_case'): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/types/form-data/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/types/form-data/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,eAAO,MAAM,sBAAsB,ogBASE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAcR;AAMD;;GAEG;AACH,eAAO,MAAM,eAAe,oZASS,CAAC;AAEtC;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CActE;AAMD;;GAEG;AACH,eAAO,MAAM,mBAAmB,+WAQK,CAAC;AAEtC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYvE;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB,8rBAcI,CAAC;AAEtC;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAS3E;AAMD;;GAEG;AACH,eAAO,MAAM,uBAAuB,wjBAeC,CAAC;AAEtC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAMD;;GAEG;AACH,eAAO,MAAM,sBAAsB,sXASE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAWR;AAMD;;GAEG;AACH,eAAO,MAAM,qBAAqB,+TAQG,CAAC;AAEtC;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD,MAAM,CAWR;AAMD;;GAEG;AACH,eAAO,MAAM,cAAc,4QAQU,CAAC;AAEtC;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAStE;AAMD;;GAEG;AACH,eAAO,MAAM,gBAAgB,sRAMQ,CAAC;AAEtC;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,WAAW,GAAG,YAAY,GAC3C,MAAM,CAQR"}

package/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Semantic Types
+ * LLM-enhanced reference and structural types
+ */
+export { type SemanticEqualsResult, type DurationResult, type InferMeaningResult } from '../shared/types.ts';
+export { SemanticDate, type ParseDateOptions, type DatePrecision, type DateSemanticEqualsOptions, type DateLLMClientInterface, } from './date/index.ts';
+export { SemanticArray, type ArraySemanticEqualsOptions, type SemanticSearchOptions, type SummarizeOptions, type SemanticUniqueOptions, type ArrayValidateResult, type ArrayInferTypeResult, type ArrayDetectPatternResult, } from './array/index.ts';
+export { SemanticError, type ErrorClassifyResult, type ResourceSuggestion, type ReportRecommendation, type SemanticEqualsResultWithReason, type RootCauseResult, type SuggestedFix, type RecoveryStrategy, type ErrorSeverityLevel, } from './error/index.ts';
+export { SemanticPromise, type PromiseState, type PromiseStatus, type InferredOperation, type RetryOptions, type ValidationResult, type SemanticErrorAnalysis, } from './promise/index.ts';
+export { SemanticRegExp, type FromOptions as RegExpFromOptions, type TestWithExplanationResult, type SimplifyResult, type ImprovementSuggestion, type RegExpTestCases, type ValidateResultWithWarnings, type RelatedSuggestion, type InferTypeResult, } from './regexp/index.ts';
+export { SemanticURL, type URLSemanticEqualsResult, type URLClassifyResult, type URLValidateForResult, type ParsedQueryParam, type URLLLMClientInterface, } from './url/index.ts';
+export { SemanticObject, type ObjectValidateResult, type SemanticMergeOptions as ObjectSemanticMergeOptions, type KeyConvention, type SemanticEqualsResultWithMappings, type SemanticGetResult as ObjectSemanticGetResult, type InferSchemaResult, type MissingSuggestion as ObjectMissingSuggestion, type InferTypeResult as ObjectInferTypeResult, type SensitiveResult, } from './object/index.ts';
+export { SemanticMap, type SemanticMergeOptions as MapSemanticMergeOptions, type MapValidationRules, type FindKeyResult, type FindValueResult, type MapSemanticEqualsResult, type SemanticGetResult as MapSemanticGetResult, type ValidateResult, type MissingSuggestion as MapMissingSuggestion, type InferPurposeResult, } from './map/index.ts';
+export { SemanticSet, type SemanticHasResult, type SemanticAddResult, type SetSemanticEqualsResult, type SetSummarizeOptions, type SetValidateResult, type InferThemeResult, } from './set/index.ts';
+export { SemanticEventEmitter, type EventClassifyResult, type ValidateHandlersResult, type ValidateEventNameResult, type HandlerSuggestion, type AnalyzeFlowResult, type MonitorOptions, } from './event-emitter/index.ts';
+export { SemanticRequest, SemanticResponse, SemanticHeaders, type RequestSemanticEqualsResult, type RequestFilter, type RequestIntentResult, type RequestSecurityResult, type RequestLLMClientInterface, type ResponseAnalysisResult, type ResponseContract, type ErrorInterpretationResult, type ResponseLLMClientInterface, type HeadersSemanticEqualsResult, type HeaderIssue, type HeadersValidateResult, type HeaderSuggestion, type HeadersLLMClientInterface, } from './fetch/index.ts';
+export { SemanticTextEncoder, SemanticTextDecoder, SemanticTextCodec, type TextCodecLLMClientInterface, type EncodeWithAnalysisResult, type CanEncodeResult, type DetectEncodingResult, type DecodeWithAnalysisResult, type RepairMojibakeResult, type AreEquivalentResult, type TranscodeResult, type EncodingIssue, type ValidateEncodingResult, type SuggestEncodingResult, type ExplainErrorResult, } from './text-codec/index.ts';
+export { SemanticFormData, type FormDataSemanticEqualsResult, type FormDataValidateResult, type FormDataSemanticGetResult, type FormDataInferPurposeResult, type FormDataDetectSensitiveResult, type FormDataMissingSuggestion, type FileValidationRules, type FormDataFileValidateResult, type FormDataLLMClientInterface, } from './form-data/index.ts';
+export { SemanticBun, SemanticBunFileRef, analyzeServerConfig, suggestServerConfig, isCommandSafe, explainCommand, suggestSaferCommand, validateEnv, detectSensitiveEnv, getEnv, type FileTypeResult, type ServerConfigAnalysis, type CommandSafetyResult, type SaferCommandSuggestion, type EnvValidationResult, type SensitiveEnvResult, type BunLLMClientInterface, } from './bun/index.ts';
+export { SemanticBlob, SemanticFile, type BlobSemanticEqualsResult, type ContentTypeResult, type AnalyzeResult, type ValidateForResult, type SafetyResult as BlobSafetyResult, type BlobLLMClientInterface, type FilenameValidationResult, type ExtensionValidationResult, type CategoryResult, type FilenameSuggestionResult, type FileLLMClientInterface, } from './blob-file/index.ts';
+export { SemanticReadableStream, SemanticWritableStream, SemanticTransformStream, type DetectContentTypeResult, type StreamSemanticEqualsResult, type DetectPatternsResult, type InferSchemaResult as StreamInferSchemaResult, type StreamValidationItem, type WriteStats, } from './streams/index.ts';
+export { SemanticNever, type UnreachabilityType, type ExhaustiveResult, type UnreachabilityResult, type DeadCodeResult, type ExhaustiveHandlerResult, type ValidateExhaustivenessResult, type ShouldReturnNeverResult, type IntersectionAnalysisResult, type NeverPattern, } from './never/index.ts';
+export { SemanticUnknown, type BasicType, type UnknownInferTypeResult, type TypeSuggestion, type ValidateShapeResult, type GenerateTypeGuardResult, type MatchesResult, type NarrowToResult, } from './unknown/index.ts';
+export { SemanticObjectLiteral, type ObjectLiteralValidateResult, type DetectDomainResult, type PropertySearchResult, type MissingPropertySuggestion, type KeyConvention as ObjectLiteralKeyConvention, type SemanticEqualsResultWithMappings as ObjectLiteralSemanticEqualsResult, type InferSchemaResult as ObjectLiteralInferSchemaResult, type SensitiveResult as ObjectLiteralSensitiveResult, } from './object-literal/index.ts';
+export { SemanticCallable, type InferredSignature, type WrapperSuggestion, type CallableTestCase, type DetectedIssue, type SafetyResult as CallableSafetyResult, } from './callable/index.ts';
+export { SemanticConstructable, type Constructor, type ConstructableSemanticEqualsResult, type InstanceShapeResult, type CreateValidatedResult, type DocFormat, } from './constructable/index.ts';
+export { SemanticTuple, type PositionalMeaning, type InferPositionalMeaningResult, type ValidateRelationshipResult, type ToObjectResult, type GetByLabelResult, type StructureIssue, type ValidateStructureResult, type SemanticEqualsResultWithReason as TupleSemanticEqualsResult, type DetectPatternResult as TupleDetectPatternResult, } from './tuple/index.ts';
+export { SemanticRecord, type RecordSemanticEqualsResult, type ValidateKeysResult, type ValidateValuesResult, type InvalidEntry, type RecordInferPurposeResult, type SemanticGetResult as RecordSemanticGetResult, type MissingSuggestion as RecordMissingSuggestion, } from './record/index.ts';
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,6 @@
+/**
+ * SemanticMap module
+ * LLM-enhanced Map type with semantic understanding
+ */
+export { SemanticMap, type SemanticMergeOptions, type MapValidationRules, type FindKeyResult, type FindValueResult, type MapSemanticEqualsResult, type SemanticGetResult, type ValidateResult, type MissingSuggestion, type InferPurposeResult, } from './map.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/map/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC"}

package/dist/types/map/map.d.ts

@@ -0,0 +1,204 @@
+/**
+ * SemanticMap
+ * A Map type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<Map<K, V>> - Base semantic wrapper
+ * - Comparable<SemanticMap<K, V>> - Semantic equality comparison
+ * - Validatable - Validation against semantic rules
+ * - Summarizable - Content summarization
+ * - SemanticAccessible - Semantic key lookup
+ * - SemanticGroupable - Semantic grouping
+ * - PurposeInferable - Purpose inference
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticGetResult, ValidateResult, MissingSuggestion, InferPurposeResult } from '../../shared/types.ts';
+import type { Semantic, Comparable } from '../../shared/interfaces.ts';
+export type { SemanticGetResult, ValidateResult, MissingSuggestion, InferPurposeResult, } from '../../shared/types.ts';
+/** Options for semantic merge */
+export interface SemanticMergeOptions {
+    conflictResolution?: 'prefer-this' | 'prefer-other' | 'combine';
+}
+/** Validation rules for map */
+export interface MapValidationRules {
+    keys?: string;
+    values?: string;
+}
+/** Result of finding keys */
+export interface FindKeyResult<K> {
+    key: K;
+    relevance: number;
+}
+/** Result of finding values */
+export interface FindValueResult<K, V> {
+    key: K;
+    value: V;
+    relevance: number;
+}
+/** Result of semantic equality comparison for maps */
+export interface MapSemanticEqualsResult {
+    equivalent: boolean;
+    keyMappings?: [string, string][];
+    confidence: number;
+}
+/**
+ * SemanticMap - Map with LLM-powered semantic understanding
+ *
+ * Unlike traditional maps that only support exact key matching,
+ * semantic maps can look up values using natural language queries,
+ * find semantically equivalent keys, and understand key-value relationships.
+ *
+ * @template K - The type of keys in the map
+ * @template V - The type of values in the map
+ */
+export declare class SemanticMap<K, V> implements Semantic<Map<K, V>>, Comparable<SemanticMap<K, V> | Map<K, V>, MapSemanticEqualsResult> {
+    private readonly internalMap;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticMap from an existing Map or entries
+     */
+    static from<K, V>(source: Map<K, V> | Iterable<readonly [K, V]>, client?: LLMClient): SemanticMap<K, V>;
+    /**
+     * Create an empty SemanticMap
+     */
+    static empty<K, V>(client?: LLMClient): SemanticMap<K, V>;
+    /**
+     * Create a SemanticMap from key-value pairs
+     */
+    static of<K, V>(...entries: (readonly [K, V])[]): SemanticMap<K, V>;
+    /**
+     * Get the underlying Map value
+     */
+    valueOf(): Map<K, V>;
+    /**
+     * Get the size of the map
+     */
+    get size(): number;
+    /**
+     * Get a value by exact key
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if map has exact key
+     */
+    has(key: K): boolean;
+    /**
+     * Set a key-value pair (returns new SemanticMap)
+     */
+    set(key: K, value: V): SemanticMap<K, V>;
+    /**
+     * Delete a key (returns new SemanticMap)
+     */
+    delete(key: K): SemanticMap<K, V>;
+    /**
+     * Get all keys
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Get all values
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Get all entries
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Get a value using semantic key matching.
+     * Finds the key that best matches the query, not just exact matches.
+     *
+     * @param query - Key or semantic query
+     * @param context - Optional context for matching
+     * @returns Value if found with match confidence
+     */
+    semanticGet(query: string, context?: Record<string, unknown>): Promise<SemanticGetResult<K, V>>;
+    /**
+     * Check if the map contains a semantically matching key.
+     *
+     * @param query - Key or semantic query
+     * @returns Whether a matching key exists
+     */
+    semanticHas(query: string): Promise<boolean>;
+    /**
+     * Check if two maps are semantically equivalent.
+     *
+     * @param other - Map to compare with
+     * @returns Equivalence result with key mappings
+     */
+    semanticallyEquals(other: SemanticMap<K, V> | Map<K, V>): Promise<MapSemanticEqualsResult>;
+    /**
+     * Find all keys matching semantic criteria.
+     *
+     * @param criteria - Natural language criteria
+     * @returns Matching keys with relevance
+     */
+    findKeys(criteria: string): Promise<FindKeyResult<K>[]>;
+    /**
+     * Find all values matching semantic criteria.
+     *
+     * @param criteria - Natural language criteria
+     * @returns Matching entries with relevance
+     */
+    findValues(criteria: string): Promise<FindValueResult<K, V>[]>;
+    /**
+     * Merge another map with semantic key matching.
+     *
+     * @param other - Map to merge
+     * @param options - Merge options
+     * @returns Merged map
+     */
+    semanticMerge(other: Map<K, V> | SemanticMap<K, V>, options?: SemanticMergeOptions): Promise<SemanticMap<K, V>>;
+    /**
+     * Validate all key-value pairs against semantic rules.
+     *
+     * @param rules - Validation rules for keys and/or values
+     * @returns Validation result
+     */
+    validate(rules: MapValidationRules): Promise<ValidateResult>;
+    /**
+     * Suggest missing keys based on existing patterns.
+     *
+     * @returns Suggested keys with rationale
+     */
+    suggestMissingKeys(): Promise<MissingSuggestion[]>;
+    /**
+     * Group entries by semantic criteria.
+     *
+     * @param criteria - Grouping criteria
+     * @returns Map of groups
+     */
+    groupBy(criteria: string): Promise<Map<string, SemanticMap<K, V>>>;
+    /**
+     * Summarize the map contents.
+     *
+     * @returns Human-readable summary
+     */
+    summarize(): Promise<string>;
+    /**
+     * Infer the semantic purpose of this map.
+     *
+     * @returns Inferred purpose
+     */
+    inferPurpose(): Promise<InferPurposeResult>;
+    /**
+     * Execute a function for each entry
+     */
+    forEach(callback: (value: V, key: K, map: Map<K, V>) => void): void;
+    /**
+     * Clear the map (returns new empty SemanticMap)
+     */
+    clear(): SemanticMap<K, V>;
+    /**
+     * Iterator support
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): Record<string, V>;
+}
+//# sourceMappingURL=map.d.ts.map

package/dist/types/map/map.d.ts.map

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