@monlite/core 1.3.0 → 2.0.0

package/dist/index.d.cts

@@ -75,12 +75,22 @@ declare class Collection<T = Doc> {
     findManyCore(args?: FindManyArgs<T>): WithId<T>[];
     /** @internal Synchronous core of exists (used by reactivity). */
     existsCore(where: WhereInput<T> | undefined): boolean;
-    findMany(args?: FindManyArgs<T>): Promise<WithId<T>[]>;
-    findFirst(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    findMany<S extends Select<T> | undefined = undefined>(args?: Omit<FindManyArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S>[]>;
+    /** Resolve one `$lookup` spec against already-fetched rows (2 queries, no N+1). */
+    private applyLookup;
+    findFirst<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S> | null>;
     /** Alias of {@link findFirst} for Prisma familiarity. */
-    findUnique(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    findUnique<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S> | null>;
     /** Like {@link findFirst} but throws if no document matches. */
-    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<WithId<T>>;
+    findFirstOrThrow<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S>>;
     /** True if at least one document matches. */
     exists(where?: WhereInput<T>): Promise<boolean>;
     /**
@@ -299,9 +309,12 @@ interface FieldFilter<V = any> {
 }
 /** A value used directly as a filter is shorthand for `{ equals: value }`. */
 type FilterInput<V> = V | FieldFilter<V>;
+/** A dot-notation nested path, e.g. `"address.city"`. */
+type DotPath = `${string}.${string}`;
 /**
- * Where input. Known fields are typed from `T`; nested paths can also be
- * addressed with dot notation (e.g. `"address.city"`).
+ * Where input. For a **typed** collection, keys are checked against `T` (an
+ * unknown field is a type error); dot-notation nested paths are still allowed.
+ * For an **untyped** collection (`Doc`), any field is accepted (schema-free).
  */
 type WhereInput<T = Doc> = {
     [K in keyof T]?: FilterInput<T[K]>;
@@ -313,7 +326,7 @@ type WhereInput<T = Doc> = {
     OR?: WhereInput<T> | WhereInput<T>[];
     NOT?: WhereInput<T> | WhereInput<T>[];
 } & {
-    [path: string]: any;
+    [path: DotPath]: FilterInput<any>;
 };
 /** Mongo-inspired update operators. */
 interface UpdateOperators {
@@ -330,29 +343,63 @@ interface UpdateOperators {
 type UpdateData<T = Doc> = (Partial<T> & Record<string, any>) | UpdateOperators;
 type SortOrder = "asc" | "desc";
 type OrderBy<T = Doc> = ({
-    [K in keyof T]?: SortOrder;
+    [K in keyof WithId<T>]?: SortOrder;
 } & {
-    [path: string]: SortOrder;
+    [path: DotPath]: SortOrder;
 }) | Array<{
-    [path: string]: SortOrder;
+    [K in keyof WithId<T>]?: SortOrder;
+} & {
+    [path: DotPath]: SortOrder;
 }>;
 type Select<T = Doc> = {
-    [K in keyof T]?: boolean;
+    [K in keyof WithId<T>]?: boolean;
 } & {
-    [path: string]: boolean;
+    [path: DotPath]: boolean;
+};
+/** True for the schema-free `Doc` (and `any`), so typed collections opt in only. */
+type IsLoose<T> = string extends keyof T ? true : false;
+/** Keys of a select set to a truthy value (a widened `boolean` counts as truthy). */
+type SelectedKeys<S> = keyof {
+    [K in keyof S as S[K] extends false ? never : K]: K;
 };
+/**
+ * The shape `findMany`/`findFirst` return for a given `select`. Untyped (`Doc`)
+ * collections and absent/empty selects return the full document; a typed select
+ * narrows to exactly the chosen fields.
+ */
+type Projected<T, S> = IsLoose<T> extends true ? WithId<T> : [S] extends [undefined] ? WithId<T> : keyof S extends never ? WithId<T> : Pick<WithId<T>, Extract<SelectedKeys<S>, keyof WithId<T>>>;
+/**
+ * A `$lookup`-style left join: for each result, fetch matching documents from
+ * another collection and attach them. With `unwind`, emit one row per match
+ * (`$unwind`); `unwind: "preserve"` also keeps rows that have no match.
+ */
+interface LookupSpec {
+    /** The collection to join. */
+    from: string;
+    /** Field on this collection to match on. */
+    localField: string;
+    /** Field on the `from` collection to match against. */
+    foreignField: string;
+    /** Output field that receives the matched document(s). */
+    as: string;
+    /** Flatten the `as` array to a single object (one output row per match). */
+    unwind?: boolean | "preserve";
+}
 interface FindManyArgs<T = Doc> {
     where?: WhereInput<T>;
     orderBy?: OrderBy<T>;
     select?: Select<T>;
     skip?: number;
     take?: number;
+    /** Join related documents from other collections ($lookup / $unwind). */
+    lookup?: LookupSpec | LookupSpec[];
 }
 interface FindFirstArgs<T = Doc> {
     where?: WhereInput<T>;
     orderBy?: OrderBy<T>;
     select?: Select<T>;
     skip?: number;
+    lookup?: LookupSpec | LookupSpec[];
 }
 interface CreateArgs<T = Doc> {
     data: Partial<T> & Record<string, any>;
@@ -788,4 +835,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type DotPath, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type LookupSpec, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type Projected, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.d.ts

@@ -75,12 +75,22 @@ declare class Collection<T = Doc> {
     findManyCore(args?: FindManyArgs<T>): WithId<T>[];
     /** @internal Synchronous core of exists (used by reactivity). */
     existsCore(where: WhereInput<T> | undefined): boolean;
-    findMany(args?: FindManyArgs<T>): Promise<WithId<T>[]>;
-    findFirst(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    findMany<S extends Select<T> | undefined = undefined>(args?: Omit<FindManyArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S>[]>;
+    /** Resolve one `$lookup` spec against already-fetched rows (2 queries, no N+1). */
+    private applyLookup;
+    findFirst<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S> | null>;
     /** Alias of {@link findFirst} for Prisma familiarity. */
-    findUnique(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    findUnique<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S> | null>;
     /** Like {@link findFirst} but throws if no document matches. */
-    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<WithId<T>>;
+    findFirstOrThrow<S extends Select<T> | undefined = undefined>(args?: Omit<FindFirstArgs<T>, "select"> & {
+        select?: S;
+    }): Promise<Projected<T, S>>;
     /** True if at least one document matches. */
     exists(where?: WhereInput<T>): Promise<boolean>;
     /**
@@ -299,9 +309,12 @@ interface FieldFilter<V = any> {
 }
 /** A value used directly as a filter is shorthand for `{ equals: value }`. */
 type FilterInput<V> = V | FieldFilter<V>;
+/** A dot-notation nested path, e.g. `"address.city"`. */
+type DotPath = `${string}.${string}`;
 /**
- * Where input. Known fields are typed from `T`; nested paths can also be
- * addressed with dot notation (e.g. `"address.city"`).
+ * Where input. For a **typed** collection, keys are checked against `T` (an
+ * unknown field is a type error); dot-notation nested paths are still allowed.
+ * For an **untyped** collection (`Doc`), any field is accepted (schema-free).
  */
 type WhereInput<T = Doc> = {
     [K in keyof T]?: FilterInput<T[K]>;
@@ -313,7 +326,7 @@ type WhereInput<T = Doc> = {
     OR?: WhereInput<T> | WhereInput<T>[];
     NOT?: WhereInput<T> | WhereInput<T>[];
 } & {
-    [path: string]: any;
+    [path: DotPath]: FilterInput<any>;
 };
 /** Mongo-inspired update operators. */
 interface UpdateOperators {
@@ -330,29 +343,63 @@ interface UpdateOperators {
 type UpdateData<T = Doc> = (Partial<T> & Record<string, any>) | UpdateOperators;
 type SortOrder = "asc" | "desc";
 type OrderBy<T = Doc> = ({
-    [K in keyof T]?: SortOrder;
+    [K in keyof WithId<T>]?: SortOrder;
 } & {
-    [path: string]: SortOrder;
+    [path: DotPath]: SortOrder;
 }) | Array<{
-    [path: string]: SortOrder;
+    [K in keyof WithId<T>]?: SortOrder;
+} & {
+    [path: DotPath]: SortOrder;
 }>;
 type Select<T = Doc> = {
-    [K in keyof T]?: boolean;
+    [K in keyof WithId<T>]?: boolean;
 } & {
-    [path: string]: boolean;
+    [path: DotPath]: boolean;
+};
+/** True for the schema-free `Doc` (and `any`), so typed collections opt in only. */
+type IsLoose<T> = string extends keyof T ? true : false;
+/** Keys of a select set to a truthy value (a widened `boolean` counts as truthy). */
+type SelectedKeys<S> = keyof {
+    [K in keyof S as S[K] extends false ? never : K]: K;
 };
+/**
+ * The shape `findMany`/`findFirst` return for a given `select`. Untyped (`Doc`)
+ * collections and absent/empty selects return the full document; a typed select
+ * narrows to exactly the chosen fields.
+ */
+type Projected<T, S> = IsLoose<T> extends true ? WithId<T> : [S] extends [undefined] ? WithId<T> : keyof S extends never ? WithId<T> : Pick<WithId<T>, Extract<SelectedKeys<S>, keyof WithId<T>>>;
+/**
+ * A `$lookup`-style left join: for each result, fetch matching documents from
+ * another collection and attach them. With `unwind`, emit one row per match
+ * (`$unwind`); `unwind: "preserve"` also keeps rows that have no match.
+ */
+interface LookupSpec {
+    /** The collection to join. */
+    from: string;
+    /** Field on this collection to match on. */
+    localField: string;
+    /** Field on the `from` collection to match against. */
+    foreignField: string;
+    /** Output field that receives the matched document(s). */
+    as: string;
+    /** Flatten the `as` array to a single object (one output row per match). */
+    unwind?: boolean | "preserve";
+}
 interface FindManyArgs<T = Doc> {
     where?: WhereInput<T>;
     orderBy?: OrderBy<T>;
     select?: Select<T>;
     skip?: number;
     take?: number;
+    /** Join related documents from other collections ($lookup / $unwind). */
+    lookup?: LookupSpec | LookupSpec[];
 }
 interface FindFirstArgs<T = Doc> {
     where?: WhereInput<T>;
     orderBy?: OrderBy<T>;
     select?: Select<T>;
     skip?: number;
+    lookup?: LookupSpec | LookupSpec[];
 }
 interface CreateArgs<T = Doc> {
     data: Partial<T> & Record<string, any>;
@@ -788,4 +835,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type DotPath, type Driver, type DriverName, type DriverOpenOptions, type EncryptionOptions, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, type LookupSpec, type MigrateOptions, Monlite, MonliteConstraintError, MonliteEncryptionError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type Projected, type RemoteChange, type RunResult, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.js

@@ -1150,7 +1150,59 @@ var Collection = class {
     return this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params) != null;
   }
   async findMany(args = {}) {
-    return this.findManyCore(args);
+    const a = args;
+    if (!a.lookup) {
+      return this.findManyCore(a);
+    }
+    const specs = Array.isArray(a.lookup) ? a.lookup : [a.lookup];
+    let rows = this.findManyCore({
+      ...a,
+      select: void 0,
+      lookup: void 0
+    });
+    for (const spec of specs) rows = await this.applyLookup(rows, spec);
+    if (a.select) {
+      rows = rows.map((r) => {
+        const projected = project(r, a.select);
+        for (const spec of specs) projected[spec.as] = r[spec.as];
+        return projected;
+      });
+    }
+    return rows;
+  }
+  /** Resolve one `$lookup` spec against already-fetched rows (2 queries, no N+1). */
+  async applyLookup(rows, spec) {
+    const localValues = [
+      ...new Set(
+        rows.map((r) => r[spec.localField]).filter((v) => v !== void 0 && v !== null)
+      )
+    ];
+    const foreign = localValues.length ? await this.mon.collection(spec.from).findMany({
+      where: { [spec.foreignField]: { in: localValues } }
+    }) : [];
+    const byKey = /* @__PURE__ */ new Map();
+    for (const f of foreign) {
+      const key = f[spec.foreignField];
+      const list = byKey.get(key);
+      if (list) list.push(f);
+      else byKey.set(key, [f]);
+    }
+    if (spec.unwind) {
+      const out = [];
+      for (const r of rows) {
+        const matches = byKey.get(r[spec.localField]) ?? [];
+        if (matches.length === 0) {
+          if (spec.unwind === "preserve") out.push({ ...r, [spec.as]: null });
+        } else {
+          for (const m of matches) out.push({ ...r, [spec.as]: m });
+        }
+      }
+      return out;
+    }
+    return rows.map((r) => ({
+      ...r,
+      [spec.as]: byKey.get(r[spec.localField]) ?? []
+    }));
   }
   async findFirst(args = {}) {
     const rows = await this.findMany({ ...args, take: 1 });