@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/providers/BaseProvider.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The root every provider base class inherits from (#1148).
+ *
+ * It exists for one contract: a provider states what it does with data between
+ * accepting it and having it on disk. That question is not specific to
+ * auditing — a page provider that buffers its index writes, a search provider
+ * that batches, and a logging provider that flushes on a timer all have the
+ * same window in which a record can be lost, and an instance should be able to
+ * say so uniformly rather than one subsystem at a time.
+ *
+ * It carries what every provider genuinely shares, and deliberately no more:
+ * the durability contract (#1148) and its own identity (#1151).
+ *
+ * __Identity, not lifecycle.__ `ProviderInfo` was declared nine times across
+ * this tree — once canonically and eight times locally — and the copies had
+ * already drifted into three different shapes, which is the failure that made
+ * consolidating it worth doing. Every provider has a name and a version, so
+ * that belongs here.
+ *
+ * Lifecycle does NOT. `initialize()`, `shutdown()` and `isHealthy()` appear in
+ * 8, 4 and 4 of the nine base classes respectively, some abstract and some
+ * concrete, and whether a cache provider's lifecycle is genuinely the same
+ * shape as a page provider's is a design question rather than a refactor. A
+ * uniform lifecycle asserted across providers that do not have one would be
+ * the same defect as the `durable` flag #1148 removed: a contract declared for
+ * everybody and honoured by some. #1151 keeps that as its own step, undecided.
+ */
+/**
+ * What a provider does with a record before it is durably stored.
+ *
+ * Facts rather than a claim. Durability on a single node means write, fsync,
+ * then acknowledge — and even that trusts a disk controller's cache, while a
+ * failed disk takes the data with it. So a provider reports the window in
+ * which a record can still be lost and the reader draws the conclusion.
+ *
+ * The alternative was a `durable: boolean`, which is what this replaces: it
+ * was derived from an unrelated property, was true for every storing provider,
+ * and was false in fact for the one that shipped by default (#1148).
+ */
+import type { ProviderInfo } from '../types/Provider.js';
+export interface ProviderDurability {
+    /** Milliseconds a record may sit in memory before being written. 0 = never buffered. */
+    bufferedForMs: number;
+    /** Records held before an early write is forced. 0 = no bound. */
+    bufferedRecords: number;
+    /** Whether EVERY write is flushed to the device before being reported as stored. */
+    fsync: boolean;
+    /**
+     * Classes of write that ARE unbuffered and fsynced even when `fsync` is
+     * false, named in the provider's own vocabulary — for auditing, the tier
+     * (#1158).
+     *
+     * A partial guarantee needs somewhere to be stated, or it rounds to a claim
+     * that is wrong in one direction or the other: `fsync: true` would promise
+     * durability for buffered `standard` events that do not have it, and a bare
+     * `fsync: false` hides a guarantee the critical path genuinely provides.
+     * Absent when the whole answer is `fsync`.
+     */
+    fsyncedClasses?: readonly string[];
+}
+declare abstract class BaseProvider {
+    /**
+     * What this provider calls itself (#1151).
+     *
+     * `protected`, and set by a subclass in its constructor or field
+     * initialisers. A provider that sets nothing reports the class name rather
+     * than a placeholder, so the answer is never a lie — it is either what the
+     * author chose or what the runtime knows.
+     */
+    protected providerName?: string;
+    /** Version this provider reports. Defaults to `1.0.0` when unset. */
+    protected providerVersion?: string;
+    /** One line on what it does. Optional, as on the canonical type. */
+    protected providerDescription?: string;
+    /** Capability strings a manager may log or branch on. */
+    protected providerFeatures?: string[];
+    /**
+     * Identify this provider.
+     *
+     * Concrete providers may still override this — their name, version and
+     * feature list are their own data, not duplication. What moved up here is
+     * the SHAPE, so the nine copies of `ProviderInfo` become one, and so a new
+     * provider that sets the fields gets a correct answer without writing the
+     * method at all.
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * What this provider does with a record before it is durably stored.
+     *
+     * Null means the provider has not stated it — silence rather than a default.
+     * A provider that buffers and forgets to declare it must not inherit an
+     * assertion that it writes immediately, which is precisely the bug this
+     * contract replaces. A reporting layer renders null as "not stated", never
+     * as "durable".
+     */
+    getDurability(): ProviderDurability | null;
+}
+export default BaseProvider;

package/lib/src/providers/BaseProvider.js

@@ -0,0 +1,74 @@
+/**
+ * The root every provider base class inherits from (#1148).
+ *
+ * It exists for one contract: a provider states what it does with data between
+ * accepting it and having it on disk. That question is not specific to
+ * auditing — a page provider that buffers its index writes, a search provider
+ * that batches, and a logging provider that flushes on a timer all have the
+ * same window in which a record can be lost, and an instance should be able to
+ * say so uniformly rather than one subsystem at a time.
+ *
+ * It carries what every provider genuinely shares, and deliberately no more:
+ * the durability contract (#1148) and its own identity (#1151).
+ *
+ * __Identity, not lifecycle.__ `ProviderInfo` was declared nine times across
+ * this tree — once canonically and eight times locally — and the copies had
+ * already drifted into three different shapes, which is the failure that made
+ * consolidating it worth doing. Every provider has a name and a version, so
+ * that belongs here.
+ *
+ * Lifecycle does NOT. `initialize()`, `shutdown()` and `isHealthy()` appear in
+ * 8, 4 and 4 of the nine base classes respectively, some abstract and some
+ * concrete, and whether a cache provider's lifecycle is genuinely the same
+ * shape as a page provider's is a design question rather than a refactor. A
+ * uniform lifecycle asserted across providers that do not have one would be
+ * the same defect as the `durable` flag #1148 removed: a contract declared for
+ * everybody and honoured by some. #1151 keeps that as its own step, undecided.
+ */
+class BaseProvider {
+    /**
+     * What this provider calls itself (#1151).
+     *
+     * `protected`, and set by a subclass in its constructor or field
+     * initialisers. A provider that sets nothing reports the class name rather
+     * than a placeholder, so the answer is never a lie — it is either what the
+     * author chose or what the runtime knows.
+     */
+    providerName;
+    /** Version this provider reports. Defaults to `1.0.0` when unset. */
+    providerVersion;
+    /** One line on what it does. Optional, as on the canonical type. */
+    providerDescription;
+    /** Capability strings a manager may log or branch on. */
+    providerFeatures;
+    /**
+     * Identify this provider.
+     *
+     * Concrete providers may still override this — their name, version and
+     * feature list are their own data, not duplication. What moved up here is
+     * the SHAPE, so the nine copies of `ProviderInfo` become one, and so a new
+     * provider that sets the fields gets a correct answer without writing the
+     * method at all.
+     */
+    getProviderInfo() {
+        return {
+            name: this.providerName ?? this.constructor.name,
+            version: this.providerVersion ?? '1.0.0',
+            description: this.providerDescription,
+            features: this.providerFeatures ?? []
+        };
+    }
+    /**
+     * What this provider does with a record before it is durably stored.
+     *
+     * Null means the provider has not stated it — silence rather than a default.
+     * A provider that buffers and forgets to declare it must not inherit an
+     * assertion that it writes immediately, which is precisely the bug this
+     * contract replaces. A reporting layer renders null as "not stated", never
+     * as "durable".
+     */
+    getDurability() {
+        return null;
+    }
+}
+export default BaseProvider;

package/lib/src/providers/BaseSearchProvider.d.ts

@@ -0,0 +1,362 @@
+/**
+ * BaseSearchProvider - Base class for all search providers
+ *
+ * Provides the interface that all search providers must implement.
+ * Follows the provider pattern established in AttachmentManager, PageManager, CacheManager, and AuditManager.
+ *
+ * Search providers implement different search engines (Lunr.js, Elasticsearch, etc.)
+ *
+ * @class BaseSearchProvider
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Whether provider has been initialized
+ *
+ * @see {@link LunrSearchProvider} for Lunr.js implementation
+ * @see {@link SearchManager} for usage
+ *
+ * Related: GitHub Issue #102 - Configuration reorganization
+ */
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { ProviderInfo } from '../types/Provider.js';
+import BaseProvider from './BaseProvider.js';
+/**
+ * Search result structure
+ */
+export interface SearchResult {
+    /** Page name/identifier */
+    name: string;
+    /** Page title */
+    title: string;
+    /** Relevance score */
+    score: number;
+    /** Content snippet with highlights */
+    snippet: string;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Minimal WikiContext shape needed by search providers to filter private results.
+ * The full WikiContext lives in src/context/WikiContext.ts.
+ *
+ * Optional method declarations match the real WikiContext API (#625) so providers
+ * can call `wikiContext.hasRole(...)` / `getPrincipals()` directly. Optional so
+ * non-WikiContext duck-typed callers (older tests, fixtures) still satisfy the type.
+ */
+export interface SearchWikiContext {
+    userContext?: {
+        username?: string;
+        roles?: string[];
+        authenticated?: boolean;
+        [key: string]: unknown;
+    };
+    hasRole?(...names: string[]): boolean;
+    getPrincipals?(): string[];
+    [key: string]: unknown;
+}
+/**
+ * Search options structure
+ */
+export interface SearchOptions {
+    /** Maximum number of results to return */
+    maxResults?: number;
+    /** Fields to search in */
+    searchIn?: string[];
+    /** Filter by categories */
+    categories?: string[];
+    /** Filter by user keywords */
+    userKeywords?: string[];
+    /** WikiContext for the current request — used to filter private search results */
+    wikiContext?: SearchWikiContext;
+    /**
+     * #884: treat the LAST query term as a prefix, for as-you-type search.
+     *
+     * Opt-in. A user who has typed "volc" wants Volcano; a user who submitted
+     * "volc" deliberately does not want every word starting with it, so this is
+     * never applied to a completed search.
+     *
+     * Only the last term is widened — earlier terms are complete words the user
+     * has finished typing.
+     */
+    prefixLastTerm?: boolean;
+}
+/**
+ * Advanced search criteria
+ */
+export interface SearchCriteria {
+    /** Search query */
+    query?: string;
+    /** Categories to filter by */
+    categories?: string[];
+    /** #706: knowledge-role values to filter by (source / citation / concept).
+     *  Pages without a `knowledge-role` set are excluded when this filter has
+     *  any entries — mirrors how `categories` excludes off-axis pages. */
+    knowledgeRoles?: string[];
+    /** User keywords to filter by */
+    userKeywords?: string[];
+    /** System keywords to filter by (auto-tagged or manually set — #507/#509) */
+    systemKeywords?: string[];
+    /** Editorial lifecycle states to filter by (draft/review/published — #893).
+     *  Pages without a `status` count as 'published'. */
+    statuses?: string[];
+    /** Fields to search in (title, content, category, keywords, or all) */
+    searchIn?: string[];
+    /** Author to filter by (page creator — matches metadata.author) */
+    author?: string;
+    /** Editor to filter by (last modifier — matches metadata.editor) */
+    editor?: string;
+    /** Date range */
+    dateRange?: {
+        from?: string;
+        to?: string;
+    };
+    /** Maximum results to return */
+    maxResults?: number;
+    /** Additional criteria */
+    [key: string]: unknown;
+}
+/**
+ * Search statistics
+ */
+export interface SearchStatistics {
+    /** Total number of indexed documents */
+    documentCount: number;
+    /** Index size in bytes */
+    indexSize?: number;
+    /** Last index update timestamp */
+    lastIndexUpdate?: string;
+    /** Additional statistics */
+    [key: string]: unknown;
+}
+/**
+ * Backup data structure
+ */
+export interface BackupData {
+    /** Provider class name */
+    provider: string;
+    /** Whether provider was initialized */
+    initialized: boolean;
+    /** Backup timestamp */
+    timestamp: string;
+    /** Additional backup data */
+    [key: string]: unknown;
+}
+/**
+ * BaseSearchProvider - Abstract base class for search providers
+ *
+ * All search providers must extend this class and implement its abstract methods.
+ * Provides a consistent interface for different search backend implementations.
+ *
+ * @abstract
+ */
+declare abstract class BaseSearchProvider extends BaseProvider {
+    /** Reference to the wiki engine */
+    protected engine: WikiEngine;
+    /** Whether provider has been initialized */
+    protected initialized: boolean;
+    /**
+     * Creates a new BaseSearchProvider instance
+     *
+     * @param engine - Reference to the WikiEngine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the search provider
+     *
+     * Implementations should load configuration from ConfigurationManager
+     * and prepare the search backend for use.
+     *
+     * @returns Promise that resolves when initialization is complete
+     * @abstract
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Get provider information
+     *
+     * Returns metadata about this provider implementation including
+     * name, version, description, and supported features.
+     *
+     * @returns Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Build or rebuild the search index from all pages
+     *
+     * Implementations should iterate through all pages and create
+     * a complete search index from scratch.
+     *
+     * @returns Promise that resolves when index building is complete
+     * @abstract
+     */
+    abstract buildIndex(): Promise<void>;
+    /**
+     * Search for pages matching the query
+     *
+     * Performs a search against the index using the provided query
+     * and optional search options.
+     *
+     * @param query - Search query string
+     * @param options - Search options for filtering and limiting results
+     * @returns Promise resolving to array of search results
+     * @abstract
+     */
+    abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Advanced search with multiple criteria
+     *
+     * Performs a more complex search using multiple criteria including
+     * query, categories, keywords, author, date range, etc.
+     *
+     * @param criteria - Search criteria object
+     * @returns Promise resolving to array of search results
+     * @abstract
+     */
+    abstract advancedSearch(criteria?: SearchCriteria): Promise<SearchResult[]>;
+    /**
+     * Get search suggestions for autocomplete
+     *
+     * Provides search term suggestions based on a partial input,
+     * useful for implementing autocomplete functionality.
+     *
+     * @param partial - Partial search term
+     * @returns Promise resolving to array of suggested completions
+     * @abstract
+     */
+    abstract getSuggestions(partial: string): Promise<string[]>;
+    /**
+     * Suggest similar pages based on content
+     *
+     * Finds pages similar to the specified page based on content
+     * analysis and relevance scoring.
+     *
+     * @param pageName - Source page name to find similar pages for
+     * @param limit - Maximum number of suggestions to return (default: 5)
+     * @returns Promise resolving to array of suggested similar pages
+     * @abstract
+     */
+    abstract suggestSimilarPages(pageName: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Add or update a page in the search index
+     *
+     * Updates the search index with the latest content and metadata
+     * for the specified page.
+     *
+     * @param pageName - Page name to update
+     * @param pageData - Page data including content and metadata
+     * @returns Promise that resolves when update is complete
+     * @abstract
+     */
+    abstract updatePageInIndex(pageName: string, pageData: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove a page from the search index
+     *
+     * Removes all entries for the specified page from the search index.
+     *
+     * @param pageName - Page name to remove
+     * @returns Promise that resolves when removal is complete
+     * @abstract
+     */
+    abstract removePageFromIndex(pageName: string): Promise<void>;
+    /**
+     * Get all unique categories from indexed documents
+     *
+     * Extracts and returns a list of all unique categories
+     * found in the indexed pages.
+     *
+     * @returns Promise resolving to array of unique category names
+     * @abstract
+     */
+    abstract getAllCategories(): Promise<string[]>;
+    /**
+     * Get all unique user keywords from indexed documents
+     *
+     * Extracts and returns a list of all unique user-defined keywords
+     * found in the indexed pages.
+     *
+     * @returns Promise resolving to array of unique keywords
+     * @abstract
+     */
+    abstract getAllUserKeywords(): Promise<string[]>;
+    /**
+     * Search by category only
+     *
+     * Finds all pages that belong to the specified category.
+     *
+     * @param category - Category name to search for
+     * @returns Promise resolving to array of pages in the category
+     * @abstract
+     */
+    abstract searchByCategory(category: string): Promise<SearchResult[]>;
+    /**
+     * Search by user keywords only
+     *
+     * Finds all pages that have the specified user keyword.
+     *
+     * @param keyword - Keyword to search for
+     * @returns Promise resolving to array of pages with the keyword
+     * @abstract
+     */
+    abstract searchByUserKeywords(keyword: string): Promise<SearchResult[]>;
+    /**
+     * Get search statistics
+     *
+     * Returns statistics about the search index including document count,
+     * index size, last update time, and other metrics.
+     *
+     * @returns Promise resolving to search statistics object
+     * @abstract
+     */
+    abstract getStatistics(): Promise<SearchStatistics>;
+    /**
+     * Get the total number of indexed documents
+     *
+     * Returns a count of how many documents are currently in the index.
+     *
+     * @returns Promise resolving to document count
+     * @abstract
+     */
+    abstract getDocumentCount(): Promise<number>;
+    /**
+     * Check if the search provider is healthy/functional
+     *
+     * Performs health checks on the search backend to verify it's
+     * operational and responding correctly.
+     *
+     * @returns Promise resolving to true if healthy, false otherwise
+     * @abstract
+     */
+    abstract isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the search provider
+     *
+     * Performs cleanup operations such as closing connections,
+     * flushing buffers, and releasing resources.
+     *
+     * @returns Promise that resolves when cleanup is complete
+     * @abstract
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Backup search index and configuration (optional)
+     *
+     * Creates a backup of the search index and configuration data.
+     * Default implementation provides basic metadata.
+     * Subclasses should override to include actual index data.
+     *
+     * @returns Promise resolving to backup data object
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore search index from backup (optional)
+     *
+     * Restores the search index from previously created backup data.
+     * Default implementation does nothing.
+     * Subclasses can override if they support restore functionality.
+     *
+     * @param _backupData - Backup data to restore from
+     * @returns Promise that resolves when restore is complete
+     */
+    restore(_backupData: BackupData): Promise<void>;
+}
+export default BaseSearchProvider;
+export { WikiEngine, ProviderInfo };