@proseql/core 0.1.0

package/dist/types/reactive-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Reactive query types for live subscriptions to data changes.
+ * Enables watch() and watchById() methods that emit streams of results
+ * whenever the underlying data changes.
+ */
+import type { PopulateConfig, SelectConfig, SortConfig, WhereClause } from "./types.js";
+/**
+ * Represents a mutation event that occurred on a collection.
+ * Published by CRUD operations and file watchers to notify reactive subscriptions.
+ *
+ * - "create": One or more entities were created
+ * - "update": One or more entities were updated
+ * - "delete": One or more entities were deleted
+ * - "reload": Data was reloaded from disk (file watcher detected external change)
+ */
+export interface ChangeEvent {
+    readonly collection: string;
+    readonly operation: "create" | "update" | "delete" | "reload";
+}
+/**
+ * Configuration for reactive watch queries.
+ * Mirrors QueryConfig but excludes cursor pagination (watches are continuous streams).
+ *
+ * @template T - The entity type being watched
+ * @template Relations - Relationship definitions for the collection
+ * @template DB - The full database type (for cross-collection type resolution)
+ */
+export type WatchConfig<T, Relations extends Record<string, unknown> = Record<string, never>, DB = unknown> = {
+    readonly where?: WhereClause<T, Relations, DB>;
+    readonly sort?: SortConfig<T, Relations, Record<string, never>, DB>;
+    readonly select?: SelectConfig<T, Relations, DB>;
+    readonly limit?: number;
+    readonly offset?: number;
+} | {
+    readonly populate: PopulateConfig<Relations, DB>;
+    readonly where?: WhereClause<T, Relations, DB>;
+    readonly sort?: SortConfig<T, Relations, {
+        populate: PopulateConfig<Relations, DB>;
+    }, DB>;
+    readonly select?: SelectConfig<T, Relations, DB>;
+    readonly limit?: number;
+    readonly offset?: number;
+};
+/**
+ * Signature for the watch() method on collections.
+ *
+ * Creates a reactive subscription that emits the current result set immediately,
+ * then re-emits whenever the underlying data changes (create/update/delete/reload).
+ *
+ * The stream is scoped: it subscribes to change notifications on creation and
+ * automatically unsubscribes when the scope closes or the stream is interrupted.
+ *
+ * @template T - The entity type being watched
+ * @template Relations - Relationship definitions for the collection
+ * @template DB - The full database type (for cross-collection type resolution)
+ * @param config - Optional query configuration (where, sort, select, limit, offset, populate)
+ * @returns A scoped Effect that produces a Stream of result arrays
+ */
+export type WatchMethod<T, Relations extends Record<string, unknown> = Record<string, never>, DB = unknown> = <C extends WatchConfig<T, Relations, DB>>(config?: C) => import("effect").Effect.Effect<import("effect").Stream.Stream<ReadonlyArray<T>, never, never>, never, import("effect").Scope.Scope>;
+/**
+ * Signature for the watchById() method on collections.
+ *
+ * Creates a reactive subscription for a single entity by ID.
+ * Emits the entity immediately if it exists (or null if not), then re-emits
+ * whenever the entity is created, updated, or deleted.
+ *
+ * The stream is scoped: it subscribes to change notifications on creation and
+ * automatically unsubscribes when the scope closes or the stream is interrupted.
+ *
+ * @template T - The entity type being watched
+ * @param id - The entity ID to watch
+ * @returns A scoped Effect that produces a Stream of T | null
+ */
+export type WatchByIdMethod<T> = (id: string) => import("effect").Effect.Effect<import("effect").Stream.Stream<T | null, never, never>, never, import("effect").Scope.Scope>;
+//# sourceMappingURL=reactive-types.d.ts.map

package/dist/types/reactive-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-types.d.ts","sourceRoot":"","sources":["../../src/types/reactive-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACX,MAAM,YAAY,CAAC;AAMpB;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAC9D;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CACtB,CAAC,EACD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACjE,EAAE,GAAG,OAAO,IAEX;IACA,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxB,GAED;IACA,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CACzB,CAAC,EACD,SAAS,EACT;QAAE,QAAQ,EAAE,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;KAAE,EAC3C,EAAE,CACF,CAAC;IACF,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMJ;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,CACtB,CAAC,EACD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACjE,EAAE,GAAG,OAAO,IACT,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAC3C,MAAM,CAAC,EAAE,CAAC,KACN,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,CAClC,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,EAC9D,KAAK,EACL,OAAO,QAAQ,EAAE,KAAK,CAAC,KAAK,CAC5B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAChC,EAAE,EAAE,MAAM,KACN,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,CAClC,OAAO,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EACtD,KAAK,EACL,OAAO,QAAQ,EAAE,KAAK,CAAC,KAAK,CAC5B,CAAC"}

package/dist/types/reactive-types.js

@@ -0,0 +1,7 @@
+/**
+ * Reactive query types for live subscriptions to data changes.
+ * Enables watch() and watchById() methods that emit streams of results
+ * whenever the underlying data changes.
+ */
+export {};
+//# sourceMappingURL=reactive-types.js.map

package/dist/types/reactive-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-types.js","sourceRoot":"","sources":["../../src/types/reactive-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/types/schema-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Effect Schema type utilities for the database.
+ *
+ * Provides helper types for working with Effect Schema in entity definitions.
+ * All entity schemas are Schema.Struct-based and support bidirectional encode/decode.
+ */
+import type { Schema } from "effect";
+/**
+ * Constraint for entity schemas: the decoded Type must include `{ readonly id: string }`.
+ * The Encoded and Context parameters are left open so schemas with transformations
+ * (e.g., DateFromString) or context requirements are accepted.
+ *
+ * Usage:
+ * ```ts
+ * const UserSchema = Schema.Struct({
+ *   id: Schema.String,
+ *   name: Schema.String,
+ *   age: Schema.Number,
+ * })
+ *
+ * // Satisfies EntitySchema because Type includes { id: string }
+ * type Check = typeof UserSchema extends EntitySchema<Schema.Schema.Type<typeof UserSchema>> ? true : false
+ * ```
+ */
+export type EntitySchema<T extends {
+    readonly id: string;
+}> = Schema.Schema<T, unknown, never>;
+/**
+ * Extract the runtime (decoded) type from a schema.
+ * This is the type that queries return and CRUD operations work with.
+ *
+ * Usage:
+ * ```ts
+ * const UserSchema = Schema.Struct({ id: Schema.String, name: Schema.String })
+ * type User = InferEntity<typeof UserSchema>
+ * // => { readonly id: string; readonly name: string }
+ * ```
+ */
+export type InferEntity<S extends Schema.Schema.All> = Schema.Schema.Type<S>;
+/**
+ * Extract the encoded (on-disk) type from a schema.
+ * This is the type stored in JSON/YAML files.
+ *
+ * For simple schemas (String, Number, etc.) this matches the runtime type.
+ * For schemas with transformations (e.g., Schema.DateFromSelf) the encoded
+ * type may differ (e.g., string on disk vs Date at runtime).
+ *
+ * Usage:
+ * ```ts
+ * const UserSchema = Schema.Struct({ id: Schema.String, name: Schema.String })
+ * type UserEncoded = InferEncoded<typeof UserSchema>
+ * // => { readonly id: string; readonly name: string }
+ * ```
+ */
+export type InferEncoded<S extends Schema.Schema.All> = Schema.Schema.Encoded<S>;
+//# sourceMappingURL=schema-types.d.ts.map

package/dist/types/schema-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-types.d.ts","sourceRoot":"","sources":["../../src/types/schema-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,IAAI,MAAM,CAAC,MAAM,CAC1E,CAAC,EACD,OAAO,EACP,KAAK,CACL,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,IACnD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/types/schema-types.js

@@ -0,0 +1,8 @@
+/**
+ * Effect Schema type utilities for the database.
+ *
+ * Provides helper types for working with Effect Schema in entity definitions.
+ * All entity schemas are Schema.Struct-based and support bidirectional encode/decode.
+ */
+export {};
+//# sourceMappingURL=schema-types.js.map

package/dist/types/schema-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-types.js","sourceRoot":"","sources":["../../src/types/schema-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/search-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Types for full-text search functionality.
+ *
+ * Provides types for search configuration, relevance scoring,
+ * and inverted index structures for text search operations.
+ */
+/**
+ * Configuration for multi-field search queries.
+ * Used with the top-level $search operator in where clauses.
+ *
+ * @example
+ * ```ts
+ * // Search across specific fields
+ * const config: SearchConfig = {
+ *   query: "herbert dune",
+ *   fields: ["title", "author"],
+ * }
+ *
+ * // Search across all string fields (fields omitted)
+ * const config2: SearchConfig = {
+ *   query: "science fiction",
+ * }
+ * ```
+ */
+export interface SearchConfig {
+    /**
+     * The search query string.
+     * Will be tokenized and matched against field values.
+     */
+    readonly query: string;
+    /**
+     * Optional list of fields to search.
+     * If omitted, all string fields on the entity are searched.
+     */
+    readonly fields?: ReadonlyArray<string>;
+}
+/**
+ * Represents the relevance score for a single entity.
+ * Used for ranking search results by relevance.
+ */
+export interface SearchScore {
+    /**
+     * The ID of the entity this score belongs to.
+     */
+    readonly entityId: string;
+    /**
+     * The computed relevance score.
+     * Higher scores indicate better matches.
+     * Score of 0 indicates no match.
+     */
+    readonly score: number;
+}
+/**
+ * Type alias for the inverted index structure used in full-text search.
+ *
+ * Maps tokens to sets of entity IDs that contain those tokens.
+ * This enables fast lookup of candidate entities for a given search term.
+ *
+ * @example
+ * ```ts
+ * // Example index structure:
+ * // "dune" -> Set(["book-1", "book-7"])
+ * // "gibson" -> Set(["book-3"])
+ * // "left" -> Set(["book-2"])
+ * ```
+ */
+export type SearchIndexMap = Map<string, Set<string>>;
+/**
+ * Key used to store computed search relevance scores on entities.
+ * This metadata is attached after filtering and consumed by the sort stage.
+ *
+ * @internal
+ */
+export declare const SEARCH_SCORE_KEY: "_searchScore";
+/**
+ * Common English stop words that can optionally be filtered from search queries.
+ * These words are typically too common to be useful for search relevance.
+ *
+ * Includes: articles, prepositions, conjunctions, and common verbs.
+ */
+export declare const STOP_WORDS: ReadonlySet<string>;
+//# sourceMappingURL=search-types.d.ts.map

package/dist/types/search-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-types.d.ts","sourceRoot":"","sources":["../../src/types/search-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACxC;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAUtD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAG,cAAuB,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAmFzC,CAAC"}

package/dist/types/search-types.js

@@ -0,0 +1,110 @@
+/**
+ * Types for full-text search functionality.
+ *
+ * Provides types for search configuration, relevance scoring,
+ * and inverted index structures for text search operations.
+ */
+// ============================================================================
+// Stop Words
+// ============================================================================
+// ============================================================================
+// Metadata Keys
+// ============================================================================
+/**
+ * Key used to store computed search relevance scores on entities.
+ * This metadata is attached after filtering and consumed by the sort stage.
+ *
+ * @internal
+ */
+export const SEARCH_SCORE_KEY = "_searchScore";
+/**
+ * Common English stop words that can optionally be filtered from search queries.
+ * These words are typically too common to be useful for search relevance.
+ *
+ * Includes: articles, prepositions, conjunctions, and common verbs.
+ */
+export const STOP_WORDS = new Set([
+    // Articles
+    "a",
+    "an",
+    "the",
+    // Prepositions
+    "at",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "of",
+    "off",
+    "on",
+    "onto",
+    "out",
+    "over",
+    "to",
+    "up",
+    "with",
+    // Conjunctions
+    "and",
+    "but",
+    "or",
+    "nor",
+    "so",
+    "yet",
+    // Common verbs
+    "am",
+    "are",
+    "be",
+    "been",
+    "being",
+    "did",
+    "do",
+    "does",
+    "doing",
+    "done",
+    "had",
+    "has",
+    "have",
+    "having",
+    "is",
+    "it",
+    "its",
+    "was",
+    "were",
+    // Pronouns
+    "he",
+    "her",
+    "him",
+    "his",
+    "i",
+    "me",
+    "my",
+    "she",
+    "that",
+    "them",
+    "they",
+    "this",
+    "us",
+    "we",
+    "what",
+    "which",
+    "who",
+    "you",
+    "your",
+    // Other common words
+    "as",
+    "if",
+    "not",
+    "no",
+    "yes",
+    "all",
+    "any",
+    "can",
+    "will",
+    "just",
+    "than",
+    "then",
+    "too",
+    "very",
+]);
+//# sourceMappingURL=search-types.js.map

package/dist/types/search-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-types.js","sourceRoot":"","sources":["../../src/types/search-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgFH,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAuB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IACtD,WAAW;IACX,GAAG;IACH,IAAI;IACJ,KAAK;IACL,eAAe;IACf,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,MAAM;IACN,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,MAAM;IACN,KAAK;IACL,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,eAAe;IACf,KAAK;IACL,KAAK;IACL,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,eAAe;IACf,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,MAAM;IACN,OAAO;IACP,KAAK;IACL,IAAI;IACJ,MAAM;IACN,OAAO;IACP,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,KAAK;IACL,MAAM;IACN,WAAW;IACX,IAAI;IACJ,KAAK;IACL,KAAK;IACL,KAAK;IACL,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,OAAO;IACP,KAAK;IACL,KAAK;IACL,MAAM;IACN,qBAAqB;IACrB,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;CACN,CAAC,CAAC"}