@nicia-ai/typegraph 0.1.0

package/dist/profiler/index.d.ts

@@ -0,0 +1,283 @@
+import { G as GraphDef, S as Store } from '../store-60Lcfi0w.js';
+import { Q as QueryAst } from '../ast-BVyihVbP.js';
+import { P as ProfilerOptions, a as ProfileReport, b as ProfileEntityType, c as PropertyTarget, U as UsageContext, d as PropertyPath, e as PropertyAccessStats, f as ProfileSummary, D as DeclaredIndex, I as IndexRecommendation } from '../types-D_3mEv2y.js';
+export { R as RecommendationPriority } from '../types-D_3mEv2y.js';
+import '../types-CjZ7g_7v.js';
+import 'drizzle-orm';
+import '../types-BRzHlhKC.js';
+import 'zod';
+
+/**
+ * QueryProfiler - Main profiler class.
+ *
+ * Captures query patterns from the AST and generates index recommendations.
+ * Uses Proxy to wrap Store and QueryBuilder for transparent interception.
+ */
+
+/**
+ * A Store with profiling capabilities.
+ *
+ * Behaves exactly like a regular Store but tracks all query executions.
+ * Access the profiler via the `profiler` property.
+ */
+type ProfiledStore<G extends GraphDef> = Store<G> & {
+    /** The profiler instance attached to this store */
+    readonly profiler: QueryProfiler;
+};
+/**
+ * QueryProfiler captures and analyzes query patterns.
+ *
+ * Attach to a store to automatically track all query executions,
+ * then generate reports with index recommendations.
+ *
+ * @example
+ * ```typescript
+ * import { QueryProfiler } from "@nicia-ai/typegraph/profiler";
+ *
+ * const profiler = new QueryProfiler({
+ *   declaredIndexes: [
+ *     { nodeKind: "Person", fields: ["email"], unique: true, name: "idx_email" },
+ *   ],
+ * });
+ *
+ * const profiledStore = profiler.attachToStore(store);
+ *
+ * // Run queries...
+ * await profiledStore.query()
+ *   .from("Person", "p")
+ *   .whereNode("p", (p) => p.email.eq("alice@example.com"))
+ *   .select((ctx) => ctx.p)
+ *   .execute();
+ *
+ * // Get report
+ * const report = profiler.getReport();
+ * console.log(report.recommendations);
+ * ```
+ */
+declare class QueryProfiler {
+    #private;
+    constructor(options?: ProfilerOptions);
+    /**
+     * Records a query execution from its AST.
+     *
+     * This is called automatically when attached to a store.
+     * Can also be called manually for custom integrations.
+     *
+     * @param ast - The query AST to analyze
+     */
+    recordQuery(ast: QueryAst): void;
+    /**
+     * Attaches the profiler to a store.
+     *
+     * Returns a wrapped store that tracks all query executions.
+     * The wrapped store behaves identically to the original.
+     *
+     * @param store - The store to attach to
+     * @returns A profiled store with the `profiler` property
+     * @throws Error if the profiler is already attached to another store
+     */
+    attachToStore<G extends GraphDef>(store: Store<G>): ProfiledStore<G>;
+    /**
+     * Generates a complete profile report.
+     *
+     * The report includes:
+     * - All property access patterns with frequency and context
+     * - Index recommendations sorted by priority
+     * - List of unindexed filter properties
+     * - Summary statistics
+     *
+     * @returns The profile report
+     */
+    getReport(): ProfileReport;
+    /**
+     * Checks if all filtered properties are covered by indexes.
+     *
+     * Throws an error if any filtered properties lack indexes.
+     * Useful for test assertions to ensure query performance.
+     *
+     * @throws Error if unindexed filter properties are found
+     *
+     * @example
+     * ```typescript
+     * // In your test file
+     * it("all filtered properties should be indexed", () => {
+     *   profiler.assertIndexCoverage();
+     * });
+     * ```
+     */
+    assertIndexCoverage(): void;
+    /**
+     * Resets all collected data.
+     *
+     * Clears patterns and query count. Useful for starting a fresh
+     * profiling session without creating a new profiler instance.
+     */
+    reset(): void;
+    /**
+     * Marks the profiler as detached.
+     *
+     * Call this when you're done profiling to allow reattachment
+     * to the same or a different store.
+     */
+    detach(): void;
+    /**
+     * Whether the profiler is currently attached to a store.
+     */
+    get isAttached(): boolean;
+}
+
+/**
+ * AST Extractor - Extracts property access patterns from QueryAst.
+ *
+ * Walks the query AST to identify all property accesses and their
+ * usage contexts (filter, sort, select, groupBy).
+ */
+
+/**
+ * A property access extracted from the AST.
+ */
+type ExtractedAccess = Readonly<{
+    /** Whether the access targets nodes or edges */
+    entityType: ProfileEntityType;
+    /** Expanded kind names for the alias */
+    kindNames: readonly string[];
+    /** The accessed target (props pointer or system field) */
+    target: PropertyTarget;
+    /** How the property was used */
+    context: UsageContext;
+    /** Predicate type if used in a filter (eq, contains, gt, etc.) */
+    predicateType?: string;
+}>;
+/**
+ * Extracts all property accesses from a QueryAst.
+ *
+ * Walks the AST to find all property references and categorizes
+ * them by usage context (filter, sort, select, groupBy).
+ *
+ * @param ast - The query AST to analyze
+ * @returns Array of extracted property accesses
+ */
+declare function extractPropertyAccesses(ast: QueryAst): readonly ExtractedAccess[];
+
+/**
+ * ProfileCollector - Aggregates property access patterns.
+ *
+ * Mutable collector that tracks property access patterns across queries
+ * and provides immutable snapshots for reporting.
+ */
+
+/**
+ * Converts a PropertyPath to a string key for Map storage.
+ *
+ * @example
+ * ```typescript
+ * pathToKey({
+ *   entityType: "node",
+ *   kind: "Person",
+ *   target: { __type: "prop", pointer: "/email" },
+ * })
+ * // => "node:Person:/email"
+ * ```
+ */
+declare function pathToKey(path: PropertyPath): string;
+/**
+ * Parses a key back to a PropertyPath.
+ *
+ * @example
+ * ```typescript
+ * keyToPath("node:Person:/email")
+ * // => { entityType: "node", kind: "Person", target: { __type: "prop", pointer: "/email" } }
+ * ```
+ */
+declare function keyToPath(key: string): PropertyPath;
+/**
+ * Collects and aggregates property access patterns.
+ *
+ * This class is mutable internally but provides immutable snapshots
+ * via `getPatterns()` and `getSummary()`.
+ *
+ * @example
+ * ```typescript
+ * const collector = new ProfileCollector();
+ *
+ * collector.record(
+ *   { nodeKind: "Person", fieldPath: ["email"] },
+ *   "filter",
+ *   "eq"
+ * );
+ * collector.recordQuery();
+ *
+ * const patterns = collector.getPatterns();
+ * const summary = collector.getSummary();
+ * ```
+ */
+declare class ProfileCollector {
+    #private;
+    /**
+     * Records a property access.
+     *
+     * @param path - The property path that was accessed
+     * @param context - How the property was used (filter, sort, select, groupBy)
+     * @param predicateType - Optional predicate type (eq, contains, gt, etc.)
+     */
+    record(path: PropertyPath, context: UsageContext, predicateType?: string): void;
+    /**
+     * Increments the query count.
+     * Call this once per query execution.
+     */
+    recordQuery(): void;
+    /**
+     * Gets all patterns as an immutable map.
+     *
+     * Returns a new Map with immutable stats objects.
+     */
+    getPatterns(): ReadonlyMap<string, PropertyAccessStats>;
+    /**
+     * Gets summary statistics.
+     */
+    getSummary(): ProfileSummary;
+    /**
+     * Resets all collected data.
+     *
+     * Note: This does not reset the startedAt timestamp.
+     * Create a new ProfileCollector for a fresh session.
+     */
+    reset(): void;
+}
+
+/**
+ * Index Recommendations - Generates index suggestions from usage patterns.
+ *
+ * Analyzes collected property access patterns and generates prioritized
+ * recommendations for missing indexes.
+ */
+
+type GenerateRecommendationsOptions = Readonly<{
+    minFrequencyForRecommendation?: number;
+    mediumFrequencyThreshold?: number;
+    highFrequencyThreshold?: number;
+}>;
+/**
+ * Generates index recommendations based on usage patterns.
+ *
+ * Analyzes property access patterns and returns prioritized recommendations
+ * for properties that would benefit from indexing.
+ *
+ * @param patterns - Collected property access patterns
+ * @param declaredIndexes - Indexes that already exist
+ * @param options - Threshold configuration (or legacy `minFrequency` number)
+ * @returns Sorted array of index recommendations
+ */
+declare function generateRecommendations(patterns: ReadonlyMap<string, PropertyAccessStats>, declaredIndexes: readonly DeclaredIndex[], options?: number | GenerateRecommendationsOptions): readonly IndexRecommendation[];
+/**
+ * Gets properties used in filters that lack indexes.
+ *
+ * Useful for test assertions to ensure all filtered properties are indexed.
+ *
+ * @param patterns - Collected property access patterns
+ * @param declaredIndexes - Indexes that already exist
+ * @returns Array of unindexed property paths
+ */
+declare function getUnindexedFilters(patterns: ReadonlyMap<string, PropertyAccessStats>, declaredIndexes: readonly DeclaredIndex[]): readonly PropertyPath[];
+
+export { DeclaredIndex, type ExtractedAccess, IndexRecommendation, ProfileCollector, ProfileReport, ProfileSummary, type ProfiledStore, ProfilerOptions, PropertyAccessStats, PropertyPath, QueryProfiler, UsageContext, extractPropertyAccesses, generateRecommendations, getUnindexedFilters, keyToPath, pathToKey };