querydig 0.1.0 → 0.2.0

package/dist/live/match.d.ts

@@ -0,0 +1,16 @@
+import type { QueryShape, SortKey } from '../types.js';
+import type { IndexInfo, SlowQuery } from './types.js';
+/**
+ * Resolve a collection/model name seen in code to a live table/collection name.
+ * Handles Mongoose (User → users), Prisma (user → User), Django (Book → shop_book), snake/camel case.
+ */
+export declare function resolveTable(name: string | undefined, tables: Iterable<string>): string | undefined;
+/** Does an index serve this filter + sort? Equality keys (any order) as the prefix, then sort keys in order. */
+export declare function indexCovers(index: IndexInfo, filterKeys: string[], sortKeys: SortKey[]): boolean;
+/** ESR-ordered index suggestion as a ready-to-run statement. */
+export declare function suggestIndex(adapter: 'mongodb' | 'postgres', table: string, filterKeys: string[], sortKeys: SortKey[]): string | undefined;
+/** Find the static shape that most likely produced a slow query seen by the database. */
+export declare function matchSlowQuery(q: SlowQuery, shapes: QueryShape[], shapeTables: Map<string, string>): QueryShape | undefined;
+export declare function redactUri(uri: string): string;
+/** Replace any credential that leaked into an error message. */
+export declare function redactText(text: string, uri: string): string;

package/dist/live/mongo.d.ts

@@ -0,0 +1,25 @@
+import type { QueryShape } from '../types.js';
+import type { ForeignKey, IndexInfo, LiveAdapter, LiveOptions, PlanSummary, SlowQuery, TableInfo } from './types.js';
+type Doc = Record<string, any>;
+/** Top-level field names of a filter, flattening $and / $or and skipping operators. */
+export declare function filterFields(filter: Doc | undefined): string[];
+/** Walk a winning plan (classic or SBE `queryPlan`) and summarise it. */
+export declare function summarisePlan(plan: Doc | undefined, table: string): Omit<PlanSummary, 'estRows' | 'docsExamined' | 'ms'>;
+export declare class MongoAdapter implements LiveAdapter {
+    private opts;
+    readonly name: "mongodb";
+    database: string;
+    private client;
+    private db;
+    constructor(opts: LiveOptions);
+    connect(): Promise<void>;
+    private get t();
+    tables(): Promise<TableInfo[]>;
+    indexes(tables: string[]): Promise<IndexInfo[]>;
+    foreignKeys(): Promise<ForeignKey[]>;
+    explain(shape: QueryShape, table: string): Promise<PlanSummary | null>;
+    slowQueries(slowMs: number): Promise<SlowQuery[]>;
+    warnings(): Promise<string[]>;
+    close(): Promise<void>;
+}
+export {};

package/dist/live/postgres.d.ts

@@ -0,0 +1,29 @@
+import type { QueryShape } from '../types.js';
+import type { ForeignKey, IndexInfo, LiveAdapter, LiveOptions, PlanSummary, SlowQuery, TableInfo } from './types.js';
+type Row = Record<string, any>;
+/** Summarise an EXPLAIN (FORMAT JSON) plan tree. */
+export declare function summarisePgPlan(root: Row | undefined, table: string): PlanSummary;
+export declare class PostgresAdapter implements LiveAdapter {
+    private opts;
+    readonly name: "postgres";
+    database: string;
+    private client;
+    private version;
+    private columns;
+    constructor(opts: LiveOptions);
+    connect(): Promise<void>;
+    private q;
+    tables(): Promise<TableInfo[]>;
+    indexes(): Promise<IndexInfo[]>;
+    foreignKeys(): Promise<ForeignKey[]>;
+    /** SQL to explain for a shape, or null when it can't be explained safely. */
+    explainSql(shape: QueryShape, table: string): {
+        sql: string;
+        generic: boolean;
+    } | null;
+    explain(shape: QueryShape, table: string): Promise<PlanSummary | null>;
+    slowQueries(slowMs: number): Promise<SlowQuery[]>;
+    warnings(): Promise<string[]>;
+    close(): Promise<void>;
+}
+export {};

package/dist/live/types.d.ts

@@ -0,0 +1,77 @@
+import type { QueryShape, SortKey } from '../types.js';
+export type AdapterName = 'mongodb' | 'postgres';
+export interface TableInfo {
+    name: string;
+    rows: number;
+    sizeBytes?: number;
+}
+export interface IndexInfo {
+    table: string;
+    name: string;
+    keys: SortKey[];
+    unique: boolean;
+    primary: boolean;
+    /** number of recorded uses; undefined when the database does not expose it */
+    usage?: number;
+    definition?: string;
+}
+export interface PlanSummary {
+    table: string;
+    fullScan: boolean;
+    inMemorySort: boolean;
+    indexUsed?: string;
+    estRows?: number;
+    docsExamined?: number;
+    ms?: number;
+    /** short human readable plan, e.g. "COLLSCAN" or "IXSCAN status_1 → FETCH" */
+    text: string;
+}
+export interface SlowQuery {
+    table?: string;
+    filterKeys: string[];
+    sortKeys: SortKey[];
+    meanMs: number;
+    calls: number;
+    text: string;
+    plan?: string;
+    docsExamined?: number;
+}
+export interface ForeignKey {
+    table: string;
+    column: string;
+    refTable: string;
+}
+export interface LiveData {
+    adapter: AdapterName;
+    database: string;
+    tables: Map<string, TableInfo>;
+    indexes: IndexInfo[];
+    /** plan per static shape id */
+    plans: Map<string, PlanSummary>;
+    /** static shape id -> resolved live table name */
+    shapeTables: Map<string, string>;
+    slow: SlowQuery[];
+    fks: ForeignKey[];
+    explained: number;
+    warnings: string[];
+}
+export interface LiveOptions {
+    uri: string;
+    db?: string;
+    slowMs: number;
+    explainExecute: boolean;
+    maxExplain: number;
+    timeoutMs: number;
+}
+export interface LiveAdapter {
+    readonly name: AdapterName;
+    readonly database: string;
+    connect(): Promise<void>;
+    tables(): Promise<TableInfo[]>;
+    indexes(tables: string[]): Promise<IndexInfo[]>;
+    foreignKeys(): Promise<ForeignKey[]>;
+    explain(shape: QueryShape, table: string): Promise<PlanSummary | null>;
+    slowQueries(slowMs: number): Promise<SlowQuery[]>;
+    warnings(): Promise<string[]>;
+    close(): Promise<void>;
+}