semantic-primitives 0.1.0

package/dist/types/url/url.d.ts

@@ -0,0 +1,270 @@
+/**
+ * SemanticURL - LLM-enhanced URL type with semantic understanding
+ *
+ * Extends the native JavaScript URL with semantic operations including:
+ * - Intelligent URL parsing and normalization
+ * - Context-aware equality comparison
+ * - URL classification by type and purpose
+ * - Purpose-based validation
+ * - Safety assessment
+ * - Related URL suggestions
+ *
+ * Implements shared interfaces:
+ * - Semantic<URL> - Base semantic wrapper
+ * - Comparable<URL | string> - Semantic equality comparison
+ * - Classifiable - URL type classification
+ * - Explainable - Human-readable explanations
+ */
+import type { LLMConfig, Message } from '../../llm/types.ts';
+import type { SemanticEqualsResult, ClassifyResult, SafetyResult, RelatedSuggestion } from '../../shared/types.ts';
+import type { Semantic, Comparable, Classifiable, Explainable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResult, ClassifyResult, SafetyResult, RelatedSuggestion, } from '../../shared/types.ts';
+/** Extended semantic equals result with differences list */
+export interface URLSemanticEqualsResult extends SemanticEqualsResult {
+    differences: string[];
+}
+/** Extended classify result for URLs */
+export interface URLClassifyResult extends ClassifyResult {
+    type: string;
+    resource?: string;
+    action?: string;
+}
+/** Validation result for purpose-based validation */
+export interface URLValidateForResult {
+    valid: boolean;
+    reason?: string;
+    warnings: string[];
+}
+/** Result of query parameter parsing */
+export interface ParsedQueryParam {
+    value: string;
+    meaning: string;
+}
+/** LLM client interface for dependency injection */
+export interface URLLLMClientInterface {
+    chat(options: {
+        messages: Message[];
+        systemPrompt?: string;
+    } & LLMConfig): Promise<{
+        content: string;
+    }>;
+}
+/**
+ * SemanticURL class
+ * Wraps a URL value with LLM-powered semantic operations
+ *
+ * Implements:
+ * - Semantic<URL> - valueOf() returns the URL value
+ * - Comparable<URL | string> - semanticallyEquals() for comparison
+ * - Classifiable - classify() for URL type classification
+ * - Explainable - explain() for human-readable explanations
+ *
+ * Also provides (as async methods):
+ * - validateFor() for purpose-based validation
+ * - isSafe() for safety checks
+ * - suggestRelated() for related URL suggestions
+ */
+export declare class SemanticURL implements Semantic<URL>, Comparable<URL | string, URLSemanticEqualsResult>, Classifiable<URLClassifyResult>, Explainable {
+    private readonly _value;
+    private readonly _llmClient;
+    private readonly _llmConfig?;
+    /**
+     * Create a SemanticURL instance
+     * @param value - The URL value to wrap
+     * @param llmClient - Optional LLM client for dependency injection (useful for testing)
+     * @param llmConfig - Optional LLM configuration
+     */
+    constructor(value: URL, llmClient?: URLLLMClientInterface, llmConfig?: LLMConfig);
+    /**
+     * Create a SemanticURL from a string, handling various formats.
+     *
+     * @param input - URL string, potentially incomplete or malformed
+     * @param base - Optional base URL
+     * @param llmClient - Optional LLM client for dependency injection
+     * @param llmConfig - Optional LLM configuration
+     * @returns SemanticURL instance
+     *
+     * @example
+     * SemanticURL.from("example.com") // Adds https://
+     * SemanticURL.from("/path", "https://example.com")
+     */
+    static from(input: string, base?: string, llmClient?: URLLLMClientInterface, llmConfig?: LLMConfig): SemanticURL;
+    /**
+     * Check if two URLs are semantically equivalent.
+     * Considers trailing slashes, default ports, www prefix, etc.
+     *
+     * @param other - URL to compare
+     * @returns Equivalence result with differences
+     *
+     * @example
+     * url.semanticallyEquals("https://www.example.com/")
+     * // { equivalent: true, differences: ["www prefix", "trailing slash"], confidence: 0.95 }
+     */
+    semanticallyEquals(other: string | URL, _options?: Record<string, unknown>): Promise<URLSemanticEqualsResult>;
+    /**
+     * Classify the URL by type and purpose.
+     *
+     * @returns URL classification
+     *
+     * @example
+     * url.classify()
+     * // { type: "api-endpoint", category: "rest-api", resource: "users", action: "list", confidence: 0.9 }
+     */
+    classify(): Promise<URLClassifyResult>;
+    /**
+     * Validate the URL for a specific purpose.
+     *
+     * @param purpose - Intended purpose of the URL
+     * @returns Validation result
+     *
+     * @example
+     * url.validateFor("public website")
+     * // { valid: true, warnings: ["Uses HTTP instead of HTTPS"] }
+     */
+    validateFor(purpose: string): Promise<URLValidateForResult>;
+    /**
+     * Explain what this URL points to.
+     *
+     * @param _context - Optional context for explanation (unused, for interface compatibility)
+     * @returns Human-readable description
+     *
+     * @example
+     * SemanticURL.from("https://api.github.com/users/octocat").explain()
+     * // "GitHub API endpoint to fetch the user profile for 'octocat'"
+     */
+    explain(_context?: string): Promise<string>;
+    /**
+     * Extract semantic information from URL components.
+     *
+     * @returns Extracted information
+     *
+     * @example
+     * url.extractInfo()
+     * // { service: "GitHub", resourceType: "user-profile", identifier: "octocat" }
+     */
+    extractInfo(): Promise<Record<string, string | undefined>>;
+    /**
+     * Check if the URL is safe to visit/request.
+     *
+     * @param _context - Optional context (unused, for interface compatibility)
+     * @returns Safety assessment
+     *
+     * @example
+     * url.isSafe()
+     * // { safe: false, reason: "Known phishing domain", severity: "high" }
+     */
+    isSafe(_context?: string): Promise<SafetyResult>;
+    /**
+     * Suggest the canonical form of this URL.
+     *
+     * @returns Canonical URL
+     *
+     * @example
+     * SemanticURL.from("HTTP://EXAMPLE.COM:80/path/").canonical()
+     * // SemanticURL for "https://example.com/path"
+     */
+    canonical(): Promise<SemanticURL>;
+    /**
+     * Generate variations of this URL.
+     *
+     * @returns URL variations
+     *
+     * @example
+     * url.variations()
+     * // ["https://example.com", "https://www.example.com", "http://example.com"]
+     */
+    variations(): Promise<string[]>;
+    /**
+     * Parse query parameters with semantic understanding.
+     *
+     * @returns Parsed parameters with meanings
+     *
+     * @example
+     * SemanticURL.from("https://api.example.com/search?q=test&limit=10").parseQuery()
+     * // { q: { value: "test", meaning: "search query" }, limit: { value: "10", meaning: "results limit" } }
+     */
+    parseQuery(): Promise<Record<string, ParsedQueryParam>>;
+    /**
+     * Suggest related URLs based on patterns.
+     *
+     * @returns Related URLs
+     *
+     * @example
+     * url.suggestRelated()
+     * // [{ url: "/users/octocat/repos", reason: "User's repositories" }]
+     */
+    suggestRelated(): Promise<RelatedSuggestion[]>;
+    /**
+     * Check if URL matches a pattern description.
+     *
+     * @param pattern - Pattern description
+     * @returns Match result
+     *
+     * @example
+     * url.matches("API endpoint")
+     * url.matches("image URL")
+     */
+    matches(pattern: string): Promise<boolean>;
+    /**
+     * Get the raw URL value
+     * @returns The underlying URL
+     */
+    valueOf(): URL;
+    /**
+     * Get the full URL string
+     */
+    get href(): string;
+    /**
+     * Get the protocol (e.g., "https:")
+     */
+    get protocol(): string;
+    /**
+     * Get the hostname
+     */
+    get hostname(): string;
+    /**
+     * Get the host (hostname:port)
+     */
+    get host(): string;
+    /**
+     * Get the port
+     */
+    get port(): string;
+    /**
+     * Get the pathname
+     */
+    get pathname(): string;
+    /**
+     * Get the search string (query string including ?)
+     */
+    get search(): string;
+    /**
+     * Get the search params
+     */
+    get searchParams(): URLSearchParams;
+    /**
+     * Get the hash (fragment including #)
+     */
+    get hash(): string;
+    /**
+     * Get the origin
+     */
+    get origin(): string;
+    /**
+     * Get the username
+     */
+    get username(): string;
+    /**
+     * Get the password
+     */
+    get password(): string;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): string;
+}
+//# sourceMappingURL=url.d.ts.map

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

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "semantic-primitives",
+  "version": "0.1.0",
+  "description": "TypeScript library providing LLM-enhanced primitive types with built-in semantic understanding",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./llm": {
+      "types": "./dist/llm/index.d.ts",
+      "import": "./dist/llm/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "dev": "bun run --watch src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "check": "bun run typecheck && bun run lint",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run clean && bun run check && bun run test && bun run build",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elicollinson/semantic-primitives.git"
+  },
+  "homepage": "https://github.com/elicollinson/semantic-primitives#readme",
+  "bugs": {
+    "url": "https://github.com/elicollinson/semantic-primitives/issues"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "semantic",
+    "primitives",
+    "typescript",
+    "openai",
+    "anthropic",
+    "google"
+  ],
+  "author": "Eli Collinson",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/bun": "latest",
+    "eslint": "^9.39.2",
+    "typescript": "^5",
+    "typescript-eslint": "^8.53.1"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@google/generative-ai": "^0.24.1",
+    "openai": "^6.16.0"
+  }
+}