@indiekitai/pg-complete 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+/** A single completion suggestion */
+interface Completion {
+    /** The text to insert */
+    text: string;
+    /** Type of the completion */
+    type: CompletionType;
+    /** Optional display text (if different from text) */
+    display?: string;
+    /** Optional description / metadata */
+    meta?: string;
+    /** Priority score (higher = more relevant) */
+    priority?: number;
+}
+type CompletionType = 'keyword' | 'table' | 'view' | 'column' | 'function' | 'schema' | 'database' | 'alias' | 'join' | 'datatype';
+/** Column metadata stored for each table/view */
+interface ColumnMetadata {
+    name: string;
+    datatype: string;
+    hasDefault: boolean;
+    default_: string | null;
+    foreignKeys: ForeignKey[];
+}
+/** Foreign key relationship */
+interface ForeignKey {
+    parentSchema: string;
+    parentTable: string;
+    parentColumn: string;
+    childSchema: string;
+    childTable: string;
+    childColumn: string;
+}
+/** Function metadata */
+interface FunctionMetadata {
+    schemaName: string;
+    funcName: string;
+    argNames: string[] | null;
+    argTypes: string[] | null;
+    argModes: string[] | null;
+    returnType: string;
+    isAggregate: boolean;
+    isWindow: boolean;
+    isSetReturning: boolean;
+    isExtension: boolean;
+    isPublic: boolean;
+}
+/** A table reference parsed from the SQL statement */
+interface TableReference {
+    schema: string | null;
+    name: string;
+    alias: string | null;
+    isFunction: boolean;
+}
+/** Schema metadata (tables, views, columns, functions, foreign keys) */
+interface SchemaMetadata {
+    /** schema -> table -> column[] */
+    tables: Record<string, Record<string, ColumnMetadata[]>>;
+    /** schema -> view -> column[] */
+    views: Record<string, Record<string, ColumnMetadata[]>>;
+    /** schema -> funcName -> FunctionMetadata[] */
+    functions: Record<string, Record<string, FunctionMetadata[]>>;
+    /** schema -> typeName -> null */
+    datatypes: Record<string, Record<string, null>>;
+}
+/** Options for PgCompleter */
+interface PgCompleterOptions {
+    /** Connection string or pg.Pool config */
+    connectionString?: string;
+    /** Pre-loaded metadata (skip database connection) */
+    metadata?: SchemaMetadata;
+    /** Search path schemas, default ['public'] */
+    searchPath?: string[];
+    /** Whether to qualify column names when multiple tables in scope */
+    qualifyColumns?: 'always' | 'never' | 'if_more_than_one_table';
+}
+
+/**
+ * Main completion engine — ported from pgcli's pgcompleter.py
+ */
+
+declare class PgCompleter {
+    private pool;
+    private metadata;
+    private searchPath;
+    private qualifyColumns;
+    private connectionString?;
+    constructor(connectionStringOrOpts?: string | PgCompleterOptions);
+    /** Connect to the database and load schema metadata */
+    refresh(): Promise<void>;
+    /** Close any open connections */
+    close(): Promise<void>;
+    /** Set metadata directly (for testing or pre-loaded scenarios) */
+    setMetadata(meta: SchemaMetadata, searchPath?: string[]): void;
+    /**
+     * Get completions for the given SQL text.
+     * @param text - The full SQL text typed so far
+     * @param cursorPos - Cursor position (defaults to end of text)
+     * @returns Array of completion suggestions
+     */
+    complete(text: string, cursorPos?: number): Completion[];
+    private dedup;
+    private getKeywordCompletions;
+    private getSchemaCompletions;
+    private getTableCompletions;
+    private getViewCompletions;
+    private getColumnCompletions;
+    private getFunctionCompletions;
+    private getJoinCompletions;
+    private getJoinConditionCompletions;
+    private getDatatypeCompletions;
+    /** Find columns for a table reference, searching through schemas */
+    private findColumns;
+    private matchesTable;
+    private getVisibleSchemas;
+}
+
+/**
+ * Simple SQL statement parser to understand context for completions.
+ * This is a lightweight port of pgcli's sqlcompletion.suggest_type logic.
+ * Instead of using sqlparse (Python), we do regex + token-based parsing.
+ */
+
+/** Represents the context we've determined from the SQL */
+type SuggestionContext = {
+    type: 'keyword';
+    lastToken?: string;
+} | {
+    type: 'table';
+    schema: string | null;
+} | {
+    type: 'view';
+    schema: string | null;
+} | {
+    type: 'column';
+    tableRefs: TableReference[];
+    qualifiable: boolean;
+    parent?: string;
+} | {
+    type: 'function';
+    schema: string | null;
+} | {
+    type: 'schema';
+} | {
+    type: 'from_clause';
+    schema: string | null;
+    tableRefs: TableReference[];
+} | {
+    type: 'join';
+    tableRefs: TableReference[];
+    schema: string | null;
+} | {
+    type: 'join_condition';
+    tableRefs: TableReference[];
+    parent?: string;
+} | {
+    type: 'alias';
+    aliases: string[];
+} | {
+    type: 'database';
+} | {
+    type: 'datatype';
+    schema: string | null;
+};
+/**
+ * Determine what types of completions to suggest based on SQL text.
+ */
+declare function suggestType(fullText: string, textBeforeCursor: string): SuggestionContext[];
+/**
+ * Extract table references from SQL text.
+ * Handles: FROM tbl, FROM schema.tbl, FROM tbl alias, FROM tbl AS alias,
+ * JOIN tbl, UPDATE tbl, INSERT INTO tbl, etc.
+ */
+declare function extractTables(sql: string): TableReference[];
+
+/** SQL keywords organized by category for context-aware completion */
+declare const KEYWORDS: string[];
+/** Keywords that commonly follow other keywords */
+declare const KEYWORD_TREE: Record<string, string[]>;
+/** Built-in PostgreSQL functions */
+declare const BUILTIN_FUNCTIONS: string[];
+
+export { BUILTIN_FUNCTIONS, type ColumnMetadata, type Completion, type CompletionType, type ForeignKey, type FunctionMetadata, KEYWORDS, KEYWORD_TREE, PgCompleter, type PgCompleterOptions, type SchemaMetadata, type TableReference, extractTables, suggestType };

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+/** A single completion suggestion */
+interface Completion {
+    /** The text to insert */
+    text: string;
+    /** Type of the completion */
+    type: CompletionType;
+    /** Optional display text (if different from text) */
+    display?: string;
+    /** Optional description / metadata */
+    meta?: string;
+    /** Priority score (higher = more relevant) */
+    priority?: number;
+}
+type CompletionType = 'keyword' | 'table' | 'view' | 'column' | 'function' | 'schema' | 'database' | 'alias' | 'join' | 'datatype';
+/** Column metadata stored for each table/view */
+interface ColumnMetadata {
+    name: string;
+    datatype: string;
+    hasDefault: boolean;
+    default_: string | null;
+    foreignKeys: ForeignKey[];
+}
+/** Foreign key relationship */
+interface ForeignKey {
+    parentSchema: string;
+    parentTable: string;
+    parentColumn: string;
+    childSchema: string;
+    childTable: string;
+    childColumn: string;
+}
+/** Function metadata */
+interface FunctionMetadata {
+    schemaName: string;
+    funcName: string;
+    argNames: string[] | null;
+    argTypes: string[] | null;
+    argModes: string[] | null;
+    returnType: string;
+    isAggregate: boolean;
+    isWindow: boolean;
+    isSetReturning: boolean;
+    isExtension: boolean;
+    isPublic: boolean;
+}
+/** A table reference parsed from the SQL statement */
+interface TableReference {
+    schema: string | null;
+    name: string;
+    alias: string | null;
+    isFunction: boolean;
+}
+/** Schema metadata (tables, views, columns, functions, foreign keys) */
+interface SchemaMetadata {
+    /** schema -> table -> column[] */
+    tables: Record<string, Record<string, ColumnMetadata[]>>;
+    /** schema -> view -> column[] */
+    views: Record<string, Record<string, ColumnMetadata[]>>;
+    /** schema -> funcName -> FunctionMetadata[] */
+    functions: Record<string, Record<string, FunctionMetadata[]>>;
+    /** schema -> typeName -> null */
+    datatypes: Record<string, Record<string, null>>;
+}
+/** Options for PgCompleter */
+interface PgCompleterOptions {
+    /** Connection string or pg.Pool config */
+    connectionString?: string;
+    /** Pre-loaded metadata (skip database connection) */
+    metadata?: SchemaMetadata;
+    /** Search path schemas, default ['public'] */
+    searchPath?: string[];
+    /** Whether to qualify column names when multiple tables in scope */
+    qualifyColumns?: 'always' | 'never' | 'if_more_than_one_table';
+}
+
+/**
+ * Main completion engine — ported from pgcli's pgcompleter.py
+ */
+
+declare class PgCompleter {
+    private pool;
+    private metadata;
+    private searchPath;
+    private qualifyColumns;
+    private connectionString?;
+    constructor(connectionStringOrOpts?: string | PgCompleterOptions);
+    /** Connect to the database and load schema metadata */
+    refresh(): Promise<void>;
+    /** Close any open connections */
+    close(): Promise<void>;
+    /** Set metadata directly (for testing or pre-loaded scenarios) */
+    setMetadata(meta: SchemaMetadata, searchPath?: string[]): void;
+    /**
+     * Get completions for the given SQL text.
+     * @param text - The full SQL text typed so far
+     * @param cursorPos - Cursor position (defaults to end of text)
+     * @returns Array of completion suggestions
+     */
+    complete(text: string, cursorPos?: number): Completion[];
+    private dedup;
+    private getKeywordCompletions;
+    private getSchemaCompletions;
+    private getTableCompletions;
+    private getViewCompletions;
+    private getColumnCompletions;
+    private getFunctionCompletions;
+    private getJoinCompletions;
+    private getJoinConditionCompletions;
+    private getDatatypeCompletions;
+    /** Find columns for a table reference, searching through schemas */
+    private findColumns;
+    private matchesTable;
+    private getVisibleSchemas;
+}
+
+/**
+ * Simple SQL statement parser to understand context for completions.
+ * This is a lightweight port of pgcli's sqlcompletion.suggest_type logic.
+ * Instead of using sqlparse (Python), we do regex + token-based parsing.
+ */
+
+/** Represents the context we've determined from the SQL */
+type SuggestionContext = {
+    type: 'keyword';
+    lastToken?: string;
+} | {
+    type: 'table';
+    schema: string | null;
+} | {
+    type: 'view';
+    schema: string | null;
+} | {
+    type: 'column';
+    tableRefs: TableReference[];
+    qualifiable: boolean;
+    parent?: string;
+} | {
+    type: 'function';
+    schema: string | null;
+} | {
+    type: 'schema';
+} | {
+    type: 'from_clause';
+    schema: string | null;
+    tableRefs: TableReference[];
+} | {
+    type: 'join';
+    tableRefs: TableReference[];
+    schema: string | null;
+} | {
+    type: 'join_condition';
+    tableRefs: TableReference[];
+    parent?: string;
+} | {
+    type: 'alias';
+    aliases: string[];
+} | {
+    type: 'database';
+} | {
+    type: 'datatype';
+    schema: string | null;
+};
+/**
+ * Determine what types of completions to suggest based on SQL text.
+ */
+declare function suggestType(fullText: string, textBeforeCursor: string): SuggestionContext[];
+/**
+ * Extract table references from SQL text.
+ * Handles: FROM tbl, FROM schema.tbl, FROM tbl alias, FROM tbl AS alias,
+ * JOIN tbl, UPDATE tbl, INSERT INTO tbl, etc.
+ */
+declare function extractTables(sql: string): TableReference[];
+
+/** SQL keywords organized by category for context-aware completion */
+declare const KEYWORDS: string[];
+/** Keywords that commonly follow other keywords */
+declare const KEYWORD_TREE: Record<string, string[]>;
+/** Built-in PostgreSQL functions */
+declare const BUILTIN_FUNCTIONS: string[];
+
+export { BUILTIN_FUNCTIONS, type ColumnMetadata, type Completion, type CompletionType, type ForeignKey, type FunctionMetadata, KEYWORDS, KEYWORD_TREE, PgCompleter, type PgCompleterOptions, type SchemaMetadata, type TableReference, extractTables, suggestType };