@signaldb/core 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+<p align="center">
+  <a href="#">
+    <img src="/docs/public/logo.svg" width="150px" alt="SignalDB Logo" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/maxnowack/signaldb/releases"><img src="https://img.shields.io/github/v/release/maxnowack/signaldb?include_prereleases&label=version&sort=semver" alt="Current Version" /></a>
+  <a href="https://github.com/maxnowack/signaldb/actions"><img src="https://img.shields.io/github/checks-status/maxnowack/signaldb/main" alt="Status Checks" /></a>
+  <img src="https://img.shields.io/npm/types/signaldb" alt="TypeScript" />
+  <a href="https://app.codecov.io/gh/maxnowack/signaldb"><img src="https://img.shields.io/codecov/c/github/maxnowack/signaldb" alt="Coverage" /></a>
+  <a href="https://github.com/maxnowack/signaldb/blob/main/LICENSE"><img src="https://img.shields.io/github/license/maxnowack/signaldb" alt="License" /></a>
+  <a href="https://github.com/maxnowack/signaldb/stargazers"><img src="https://img.shields.io/github/stars/maxnowack/signaldb" alt="Stargazers" /></a>
+</p>
+
+<p align="center">
+   <a href="https://signaldb.js.org/getting-started/">Getting Started</a> |
+   <a href="https://signaldb.js.org/reference/">Reference</a>
+<p>
+
+# SignalDB
+
+SignalDB is a client-side database optimized for modern web applications. It provides an optimistic UI for creating responsive and dynamic interfaces, a MongoDB-like interface for familiarity, and robust TypeScript support to ensure type safety and accelerate development. SignalDB enables versatile local data persistence with support for various storage providers and facilitates real-time updates by gathering and synchronizing data from multiple sources. Its framework-agnostic design makes it suitable for projects of any scale, offering instant data access with minimal latency, which is ideal for applications requiring fast data handling and real-time interactions. Adapters are available for popular reactive libraries, including [Angular](https://signaldb.js.org/guides/angular/), [React](https://signaldb.js.org/guides/react/), [Solid](https://signaldb.js.org/guides/solid-js/), [Svelte](https://signaldb.js.org/guides/svelte/) and [Vue.js](https://signaldb.js.org/guides/vue/).
+
+## Installation
+
+````
+  $ npm install @signaldb/core
+````
+
+## Usage
+
+```js
+import { Collection } from '@signaldb/core'
+
+const Posts = new Collection()
+const postId = Posts.insert({ title: 'Foo', text: 'Lorem ipsum …' })
+
+Posts.updateOne({ id: postId }, { // updates the post
+  $set: {
+    title: 'New title',
+  }
+})
+
+Posts.removeOne({ id: postId }) // removes the post
+
+const cursor = collection.find({})
+
+// returns an array with all documents in the collection
+// reruns automatically in a reactive context
+console.log(cursor.fetch())
+```
+
+See the [documentation](https://signaldb.js.org/) for more information.
+
+## License
+Licensed under MIT license. Copyright (c) 2024 Max Nowack
+
+## Contributions
+Contributions are welcome. Please open issues and/or file Pull Requests.
+See [Contributing.md](https://github.com/maxnowack/signaldb/blob/main/CONTRIBUTING.md) to get started.
+
+## Troubleshooting
+
+If you encounter any issues, there are several ways to get support.
+- Join our [Discord server](https://discord.gg/MB4ZGJX7).
+- [Start a discussion](https://github.com/maxnowack/signaldb/discussions/new/choose)
+- [Open an issue](https://github.com/maxnowack/signaldb/issues/new)

package/dist/.vite/manifest.json

@@ -0,0 +1,222 @@
+{
+  "../../../node_modules/tslib/tslib.es6.mjs": {
+    "file": "index.cjs24.js",
+    "name": "node_modules/tslib/tslib.es6",
+    "src": "../../../node_modules/tslib/tslib.es6.mjs"
+  },
+  "src/AutoFetchCollection.ts": {
+    "file": "index.cjs3.js",
+    "name": "packages/base/core/src/AutoFetchCollection",
+    "src": "src/AutoFetchCollection.ts",
+    "imports": [
+      "src/ReplicatedCollection.ts",
+      "src/utils/createSignal.ts"
+    ]
+  },
+  "src/Collection/Cursor.ts": {
+    "file": "index.cjs18.js",
+    "name": "packages/base/core/src/Collection/Cursor",
+    "src": "src/Collection/Cursor.ts",
+    "imports": [
+      "src/utils/sortItems.ts",
+      "src/utils/project.ts",
+      "src/Collection/Observer.ts"
+    ]
+  },
+  "src/Collection/Observer.ts": {
+    "file": "index.cjs23.js",
+    "name": "packages/base/core/src/Collection/Observer",
+    "src": "src/Collection/Observer.ts",
+    "imports": [
+      "src/utils/isEqual.ts",
+      "src/utils/uniqueBy.ts"
+    ]
+  },
+  "src/Collection/createIndex.ts": {
+    "file": "index.cjs12.js",
+    "name": "packages/base/core/src/Collection/createIndex",
+    "src": "src/Collection/createIndex.ts",
+    "imports": [
+      "src/createIndexProvider.ts",
+      "src/utils/get.ts",
+      "src/utils/getMatchingKeys.ts",
+      "src/utils/serializeValue.ts"
+    ]
+  },
+  "src/Collection/getIndexInfo.ts": {
+    "file": "index.cjs19.js",
+    "name": "packages/base/core/src/Collection/getIndexInfo",
+    "src": "src/Collection/getIndexInfo.ts",
+    "imports": [
+      "../../../node_modules/tslib/tslib.es6.mjs",
+      "src/utils/intersection.ts"
+    ]
+  },
+  "src/Collection/index.ts": {
+    "file": "index.cjs2.js",
+    "name": "packages/base/core/src/Collection/index",
+    "src": "src/Collection/index.ts",
+    "imports": [
+      "src/types/EventEmitter.ts",
+      "src/utils/match.ts",
+      "src/utils/modify.ts",
+      "src/utils/isEqual.ts",
+      "src/utils/randomId.ts",
+      "src/utils/deepClone.ts",
+      "src/utils/serializeValue.ts",
+      "src/utils/createSignal.ts",
+      "src/Collection/Cursor.ts",
+      "src/Collection/getIndexInfo.ts",
+      "src/Collection/createIndex.ts"
+    ]
+  },
+  "src/ReplicatedCollection.ts": {
+    "file": "index.cjs20.js",
+    "name": "packages/base/core/src/ReplicatedCollection",
+    "src": "src/ReplicatedCollection.ts",
+    "imports": [
+      "src/Collection/index.ts",
+      "src/persistence/combinePersistenceAdapters.ts",
+      "src/persistence/createPersistenceAdapter.ts",
+      "src/utils/createSignal.ts"
+    ]
+  },
+  "src/createIndexProvider.ts": {
+    "file": "index.cjs5.js",
+    "name": "packages/base/core/src/createIndexProvider",
+    "src": "src/createIndexProvider.ts"
+  },
+  "src/createMemoryAdapter.ts": {
+    "file": "index.cjs6.js",
+    "name": "packages/base/core/src/createMemoryAdapter",
+    "src": "src/createMemoryAdapter.ts"
+  },
+  "src/createReactivityAdapter.ts": {
+    "file": "index.cjs8.js",
+    "name": "packages/base/core/src/createReactivityAdapter",
+    "src": "src/createReactivityAdapter.ts"
+  },
+  "src/index.ts": {
+    "file": "index.cjs.js",
+    "name": "packages/base/core/src/index",
+    "src": "src/index.ts",
+    "isEntry": true,
+    "imports": [
+      "src/Collection/index.ts",
+      "src/AutoFetchCollection.ts",
+      "src/persistence/combinePersistenceAdapters.ts",
+      "src/createIndexProvider.ts",
+      "src/createMemoryAdapter.ts",
+      "src/persistence/createPersistenceAdapter.ts",
+      "src/createReactivityAdapter.ts",
+      "src/utils/isEqual.ts",
+      "src/utils/modify.ts",
+      "src/utils/randomId.ts",
+      "src/Collection/createIndex.ts"
+    ]
+  },
+  "src/persistence/combinePersistenceAdapters.ts": {
+    "file": "index.cjs4.js",
+    "name": "packages/base/core/src/persistence/combinePersistenceAdapters",
+    "src": "src/persistence/combinePersistenceAdapters.ts",
+    "imports": [
+      "src/persistence/createPersistenceAdapter.ts"
+    ]
+  },
+  "src/persistence/createPersistenceAdapter.ts": {
+    "file": "index.cjs7.js",
+    "name": "packages/base/core/src/persistence/createPersistenceAdapter",
+    "src": "src/persistence/createPersistenceAdapter.ts"
+  },
+  "src/types/EventEmitter.ts": {
+    "file": "index.cjs13.js",
+    "name": "packages/base/core/src/types/EventEmitter",
+    "src": "src/types/EventEmitter.ts"
+  },
+  "src/utils/createSignal.ts": {
+    "file": "index.cjs17.js",
+    "name": "packages/base/core/src/utils/createSignal",
+    "src": "src/utils/createSignal.ts"
+  },
+  "src/utils/deepClone.ts": {
+    "file": "index.cjs15.js",
+    "name": "packages/base/core/src/utils/deepClone",
+    "src": "src/utils/deepClone.ts"
+  },
+  "src/utils/get.ts": {
+    "file": "index.cjs26.js",
+    "name": "packages/base/core/src/utils/get",
+    "src": "src/utils/get.ts"
+  },
+  "src/utils/getMatchingKeys.ts": {
+    "file": "index.cjs27.js",
+    "name": "packages/base/core/src/utils/getMatchingKeys",
+    "src": "src/utils/getMatchingKeys.ts",
+    "imports": [
+      "src/utils/isFieldExpression.ts",
+      "src/utils/serializeValue.ts"
+    ]
+  },
+  "src/utils/intersection.ts": {
+    "file": "index.cjs25.js",
+    "name": "packages/base/core/src/utils/intersection",
+    "src": "src/utils/intersection.ts"
+  },
+  "src/utils/isEqual.ts": {
+    "file": "index.cjs9.js",
+    "name": "packages/base/core/src/utils/isEqual",
+    "src": "src/utils/isEqual.ts"
+  },
+  "src/utils/isFieldExpression.ts": {
+    "file": "index.cjs28.js",
+    "name": "packages/base/core/src/utils/isFieldExpression",
+    "src": "src/utils/isFieldExpression.ts"
+  },
+  "src/utils/match.ts": {
+    "file": "index.cjs14.js",
+    "name": "packages/base/core/src/utils/match",
+    "src": "src/utils/match.ts"
+  },
+  "src/utils/modify.ts": {
+    "file": "index.cjs10.js",
+    "name": "packages/base/core/src/utils/modify",
+    "src": "src/utils/modify.ts"
+  },
+  "src/utils/project.ts": {
+    "file": "index.cjs22.js",
+    "name": "packages/base/core/src/utils/project",
+    "src": "src/utils/project.ts",
+    "imports": [
+      "src/utils/get.ts",
+      "src/utils/set.ts"
+    ]
+  },
+  "src/utils/randomId.ts": {
+    "file": "index.cjs11.js",
+    "name": "packages/base/core/src/utils/randomId",
+    "src": "src/utils/randomId.ts"
+  },
+  "src/utils/serializeValue.ts": {
+    "file": "index.cjs16.js",
+    "name": "packages/base/core/src/utils/serializeValue",
+    "src": "src/utils/serializeValue.ts"
+  },
+  "src/utils/set.ts": {
+    "file": "index.cjs29.js",
+    "name": "packages/base/core/src/utils/set",
+    "src": "src/utils/set.ts"
+  },
+  "src/utils/sortItems.ts": {
+    "file": "index.cjs21.js",
+    "name": "packages/base/core/src/utils/sortItems",
+    "src": "src/utils/sortItems.ts",
+    "imports": [
+      "src/utils/get.ts"
+    ]
+  },
+  "src/utils/uniqueBy.ts": {
+    "file": "index.cjs30.js",
+    "name": "packages/base/core/src/utils/uniqueBy",
+    "src": "src/utils/uniqueBy.ts"
+  }
+}

package/dist/AutoFetchCollection.d.ts

@@ -0,0 +1,60 @@
+import type { BaseItem } from './Collection';
+import type { ReplicatedCollectionOptions } from './ReplicatedCollection';
+import ReplicatedCollection from './ReplicatedCollection';
+import type Selector from './types/Selector';
+interface AutoFetchOptions<T extends {
+    id: I;
+} & Record<string, any>, I> {
+    fetchQueryItems: (selector: Selector<T>) => ReturnType<ReplicatedCollectionOptions<T, I>['pull']>;
+    purgeDelay?: number;
+    registerRemoteChange?: (onChange: () => Promise<void>) => Promise<void>;
+    mergeItems?: (itemA: T, itemB: T) => T;
+}
+export type AutoFetchCollectionOptions<T extends BaseItem<I>, I, U = T> = Omit<ReplicatedCollectionOptions<T, I, U>, 'pull' | 'registerRemoteChange'> & AutoFetchOptions<T, I>;
+/**
+ * A special collection that automatically fetches items when they are needed.
+ */
+export default class AutoFetchCollection<T extends BaseItem<I> = BaseItem, I = any, U = T> extends ReplicatedCollection<T, I, U> {
+    private activeObservers;
+    private observerTimeouts;
+    private purgeDelay;
+    private idQueryCache;
+    private itemsCache;
+    private fetchQueryItems;
+    private triggerReload;
+    private reactivityAdapter;
+    private loadingSignals;
+    private isFetchingSignal;
+    private mergeItems;
+    /**
+     * @param options {Object} - Options for the collection.
+     * @param options.fetchQueryItems {Function} - A function that fetches items from the server. It takes the selector as an argument and returns a promise that resolves to an object with an `items` property.
+     * @param options.purgeDelay {Number} - The delay in milliseconds before purging an item from the cache.
+     */
+    constructor(options: AutoFetchCollectionOptions<T, I, U>);
+    /**
+     * Registers a query manually that items should be fetched for it
+     * @param selector {Object} Selector of the query
+     */
+    registerQuery(selector: Selector<T>): void;
+    /**
+     * Unregisters a query manually that items are not fetched anymore for it
+     * @param selector {Object} Selector of the query
+     */
+    unregisterQuery(selector: Selector<T>): void;
+    private getKeyForSelector;
+    private forceRefetch;
+    private fetchSelector;
+    private handleObserverCreation;
+    private handleObserverDisposal;
+    private ensureSignal;
+    private setLoading;
+    /**
+     * Indicates wether a query is currently been loaded
+     * ⚡️ this function is reactive!
+     * @param selector {Object} Selector of the query
+     * @returns The loading state
+     */
+    isLoading(selector?: Selector<T>): boolean;
+}
+export {};

package/dist/Collection/Cursor.d.ts

@@ -0,0 +1,112 @@
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+import type { BaseItem, FindOptions, Transform } from './types';
+import type { ObserveCallbacks } from './Observer';
+/**
+ * Checks if the current scope is reactive, considering the provided reactivity adapter.
+ * @param reactivity - The reactivity adapter or a boolean indicating whether reactivity is enabled.
+ * @returns A boolean indicating if the current scope is reactive.
+ */
+export declare function isInReactiveScope(reactivity: ReactivityAdapter | undefined | false): boolean;
+export interface CursorOptions<T extends BaseItem, U = T> extends FindOptions<T> {
+    transform?: Transform<T, U>;
+    bindEvents?: (requery: () => void) => () => void;
+}
+/**
+ * Represents a cursor for querying and observing a filtered, sorted, and transformed
+ * subset of items from a collection. Supports reactivity and field tracking.
+ * @template T - The type of the items in the collection.
+ * @template U - The transformed item type after applying transformations (default is T).
+ */
+export default class Cursor<T extends BaseItem, U = T> {
+    private observer;
+    private getFilteredItems;
+    private options;
+    private onCleanupCallbacks;
+    /**
+     * Creates a new instance of the `Cursor` class.
+     * Provides utilities for querying, observing, and transforming items from a collection.
+     * @template T - The type of the items in the collection.
+     * @template U - The transformed item type after applying transformations (default is T).
+     * @param getItems - A function that retrieves the filtered list of items.
+     * @param options - Optional configuration for the cursor.
+     * @param options.transform - A transformation function to apply to each item when retrieving them.
+     * @param options.bindEvents - A function to bind reactivity events for the cursor, which should return a cleanup function.
+     * @param options.fields - A projection object defining which fields of the item should be included or excluded.
+     * @param options.sort - A sort specifier to determine the order of the items.
+     * @param options.skip - The number of items to skip from the beginning of the result set.
+     * @param options.limit - The maximum number of items to return in the result set.
+     * @param options.reactive - A reactivity adapter to enable observing changes in the cursor's result set.
+     * @param options.fieldTracking - A boolean to enable fine-grained field tracking for reactivity.
+     */
+    constructor(getItems: () => T[], options?: CursorOptions<T, U>);
+    private addGetters;
+    private transform;
+    private getItems;
+    private depend;
+    private ensureObserver;
+    private observeRawChanges;
+    /**
+     * Cleans up all resources associated with the cursor, such as reactive bindings
+     * and event listeners. This method should be called when the cursor is no longer needed
+     * to prevent memory leaks.
+     */
+    cleanup(): void;
+    /**
+     * Registers a cleanup callback to be executed when the `cleanup` method is called.
+     * Useful for managing resources and ensuring proper cleanup of bindings or listeners.
+     * @param callback - A function to be executed during cleanup.
+     */
+    onCleanup(callback: () => void): void;
+    /**
+     * Iterates over each item in the cursor's result set, applying the provided callback
+     * function to each transformed item.
+     * ⚡️ this function is reactive!
+     * @param callback - A function to execute for each item in the result set.
+     * @param callback.item - The transformed item.
+     */
+    forEach(callback: (item: U) => void): void;
+    /**
+     * Creates a new array populated with the results of applying the provided callback
+     * function to each transformed item in the cursor's result set.
+     * ⚡️ this function is reactive!
+     * @template V - The type of the items in the resulting array.
+     * @param callback - A function to execute for each item in the result set.
+     * @param callback.item - The transformed item.
+     * @returns An array of results after applying the callback to each item.
+     */
+    map<V>(callback: (item: U) => V): V[];
+    /**
+     * Fetches all transformed items from the cursor's result set as an array.
+     * Automatically applies filtering, sorting, and limiting as per the cursor's options.
+     * ⚡️ this function is reactive!
+     * @returns An array of transformed items in the result set.
+     */
+    fetch(): U[];
+    /**
+     * Counts the total number of items in the cursor's result set after applying
+     * filtering and other criteria.
+     * ⚡️ this function is reactive!
+     * @returns The total number of items in the result set.
+     */
+    count(): number;
+    /**
+     * Observes changes to the cursor's result set and triggers the specified callbacks
+     * when items are added, removed, or updated. Supports reactivity and transformation.
+     * @param callbacks - An object containing the callback functions to handle different change events.
+     * @param callbacks.added - Triggered when an item is added to the result set.
+     * @param callbacks.removed - Triggered when an item is removed from the result set.
+     * @param callbacks.changed - Triggered when an item in the result set is modified.
+     * @param callbacks.addedBefore - Triggered when an item is added before another item in the result set.
+     * @param callbacks.movedBefore - Triggered when an item is moved before another item in the result set.
+     * @param callbacks.changedField - Triggered when a specific field of an item changes.
+     * @param skipInitial - A boolean indicating whether to skip the initial notification of the current result set.
+     * @returns A function to stop observing changes.
+     */
+    observeChanges(callbacks: ObserveCallbacks<U>, skipInitial?: boolean): () => void;
+    /**
+     * Forces the cursor to re-evaluate its result set by re-fetching items
+     * from the collection. This is useful when the underlying data or query
+     * criteria have changed, and you want to ensure the cursor reflects the latest state.
+     */
+    requery(): void;
+}

package/dist/Collection/Observer.d.ts

@@ -0,0 +1,61 @@
+type AddedCallback<T> = (item: T) => void;
+type AddedBeforeCallback<T> = (item: T, before: T) => void;
+type ChangedCallback<T> = (item: T) => void;
+type ChangedFieldCallback<T> = <Field extends keyof T>(item: T, field: Field, oldValue: T[Field], newValue: T[Field]) => void;
+type MovedBeforeCallback<T> = (item: T, before: T) => void;
+type RemovedCallback<T> = (item: T) => void;
+export interface ObserveCallbacks<T> {
+    added?: AddedCallback<T>;
+    addedBefore?: AddedBeforeCallback<T>;
+    changed?: ChangedCallback<T>;
+    changedField?: ChangedFieldCallback<T>;
+    movedBefore?: MovedBeforeCallback<T>;
+    removed?: RemovedCallback<T>;
+}
+/**
+ * Represents an observer that tracks changes in a collection of items and triggers
+ * callbacks for various events such as addition, removal, and modification of items.
+ * @template T - The type of the items being observed, which must include an `id` field.
+ */
+export default class Observer<T extends {
+    id: any;
+}> {
+    private previousItems;
+    private callbacks;
+    private unbindEvents;
+    /**
+     * Creates a new instance of the `Observer` class.
+     * Sets up event bindings and initializes the callbacks for tracking changes in a collection.
+     * @param bindEvents - A function to bind external events to the observer. Must return a cleanup function to unbind those events.
+     */
+    constructor(bindEvents: () => () => void);
+    private call;
+    private hasCallbacks;
+    /**
+     * Determines if the observer has no active callbacks registered for any events.
+     * @returns A boolean indicating whether the observer is empty (i.e., no callbacks are registered).
+     */
+    isEmpty(): boolean;
+    /**
+     * Compares the previous state of items with the new state and triggers the appropriate callbacks
+     * for events such as added, removed, changed, or moved items.
+     * @param newItems - The new list of items to compare against the previous state.
+     */
+    runChecks(newItems: T[]): void;
+    /**
+     * Stops the observer by unbinding all events and cleaning up resources.
+     */
+    stop(): void;
+    /**
+     * Registers callbacks for specific events to observe changes in the collection.
+     * @param callbacks - An object containing the callbacks for various events (e.g., 'added', 'removed').
+     * @param skipInitial - A boolean indicating whether to skip invoking the callbacks for the initial state of the collection.
+     */
+    addCallbacks(callbacks: ObserveCallbacks<T>, skipInitial?: boolean): void;
+    /**
+     * Removes the specified callbacks for specific events, unregistering them from the observer.
+     * @param callbacks - An object containing the callbacks to be removed for various events.
+     */
+    removeCallbacks(callbacks: ObserveCallbacks<T>): void;
+}
+export {};

package/dist/Collection/createIndex.d.ts

@@ -0,0 +1,15 @@
+import type IndexProvider from '../types/IndexProvider';
+import type { BaseItem } from './types';
+/**
+ * creates an index for a specific field but uses an external map to store the index
+ * @param field name of the field
+ * @param index the external map to use for the index
+ * @returns an index provider to pass to the `indices` option of the collection constructor
+ */
+export declare function createExternalIndex<T extends BaseItem<I> = BaseItem, I = any>(field: string, index: Map<string, Set<number>>): IndexProvider<T, I>;
+/**
+ * creates an index for a specific field
+ * @param field name of the field
+ * @returns an index provider to pass to the `indices` option of the collection constructor
+ */
+export default function createIndex<T extends BaseItem<I> = BaseItem, I = any>(field: string): IndexProvider<T, I>;

package/dist/Collection/getIndexInfo.d.ts

@@ -0,0 +1,41 @@
+import type IndexProvider from '../types/IndexProvider';
+import type { FlatSelector } from '../types/Selector';
+import type Selector from '../types/Selector';
+import type { BaseItem } from './types';
+/**
+ * Retrieves merged index information for a given flat selector by querying multiple
+ * index providers. Combines results from all index providers to determine matched positions
+ * and an optimized selector.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param indexProviders - An array of index providers to query.
+ * @param selector - The flat selector used to filter items.
+ * @returns An object containing:
+ *   - `matched`: A boolean indicating if the selector matched any items.
+ *   - `positions`: An array of matched item positions.
+ *   - `optimizedSelector`: A flat selector optimized based on the index results.
+ */
+export declare function getMergedIndexInfo<T extends BaseItem<I> = BaseItem, I = any>(indexProviders: IndexProvider<T, I>[], selector: FlatSelector<T>): {
+    matched: boolean;
+    positions: number[];
+    optimizedSelector: FlatSelector<T>;
+};
+/**
+ * Retrieves index information for a given complex selector by querying multiple
+ * index providers. Handles nested `$and` and `$or` conditions in the selector and
+ * optimizes the selector to minimize processing overhead.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param indexProviders - An array of index providers to query.
+ * @param selector - The complex selector used to filter items.
+ * @returns An object containing:
+ *   - `matched`: A boolean indicating if the selector matched any items.
+ *   - `positions`: An array of matched item positions.
+ *   - `optimizedSelector`: A selector optimized based on the index results, with unused
+ *     conditions removed.
+ */
+export default function getIndexInfo<T extends BaseItem<I> = BaseItem, I = any>(indexProviders: IndexProvider<T, I>[], selector: Selector<T>): {
+    matched: boolean;
+    positions: number[];
+    optimizedSelector: Selector<T>;
+};