lazypock 0.13.0 → 0.15.0

package/dist/index.cjs

@@ -25,6 +25,8 @@ __export(index_exports, {
   CollectionService: () => CollectionService,
   CollectionsService: () => CollectionsService,
   FilesService: () => FilesService,
+  FilterBuilder: () => FilterBuilder,
+  FilterExpr: () => FilterExpr,
   HttpClient: () => HttpClient,
   LazypockClient: () => LazypockClient,
   RealtimeService: () => RealtimeService,
@@ -475,6 +477,144 @@ var memoryStorage = {
   }
 };
 
+// src/filter.ts
+function literal(value) {
+  if (value === null) return "null";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `[lazypock] filter: ${String(value)} is not a valid numeric value`
+      );
+    }
+    return String(value);
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+  const escaped = String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `'${escaped}'`;
+}
+var FilterExpr = class _FilterExpr {
+  /** @internal Build from a raw string — use {@link FilterBuilder} instead. */
+  constructor(raw) {
+    this.raw = raw;
+  }
+  /** Combine with `&&` (both must match). */
+  and(other) {
+    return new _FilterExpr(`(${this.raw} && ${other.raw})`);
+  }
+  /** Combine with `||` (either may match). */
+  or(other) {
+    return new _FilterExpr(`(${this.raw} || ${other.raw})`);
+  }
+  /** Negate the expression (`!(…)`). */
+  not() {
+    return new _FilterExpr(`!(${this.raw})`);
+  }
+  /** The raw filter string (used when serializing the request). */
+  toString() {
+    return this.raw;
+  }
+};
+var FilterBuilder = class {
+  /** @internal Use {@link CollectionService.where}. */
+  constructor(field) {
+    this.field = field;
+  }
+  /** `field = value` (equal). */
+  eq(value) {
+    return this.cmp("=", value);
+  }
+  /** `field != value` (not equal). */
+  neq(value) {
+    return this.cmp("!=", value);
+  }
+  /** `field ~ value` (contains / LIKE). */
+  contains(value) {
+    return this.cmp("~", value);
+  }
+  /** `field !~ value` (does not contain / NOT LIKE). */
+  notContains(value) {
+    return this.cmp("!~", value);
+  }
+  /** `field > value` (greater than). */
+  gt(value) {
+    return this.cmp(">", value);
+  }
+  /** `field >= value` (greater than or equal). */
+  gte(value) {
+    return this.cmp(">=", value);
+  }
+  /** `field < value` (less than). */
+  lt(value) {
+    return this.cmp("<", value);
+  }
+  /** `field <= value` (less than or equal). */
+  lte(value) {
+    return this.cmp("<=", value);
+  }
+  /**
+   * `field = v1 || field = v2 || …` (value is in the list).
+   *
+   * ```ts
+   * svc.where("id").in(["a", "b", "c"]);
+   * // → (id = 'a' || id = 'b' || id = 'c')
+   * ```
+   */
+  in(values) {
+    return new FilterExpr(this.chain("=", " || ", values));
+  }
+  /**
+   * `field != v1 && field != v2 && …` (value is not in the list).
+   */
+  notIn(values) {
+    return new FilterExpr(this.chain("!=", " && ", values));
+  }
+  /** Build `(field <op> v <join> field <op> v …)`, wrapped for safe composing. */
+  chain(op, join, values) {
+    if (values.length === 0) {
+      throw new Error(
+        `[lazypock] filter: ${op === "=" ? "in" : "notIn"}() requires at least one value`
+      );
+    }
+    const clauses = values.map((v) => `${this.field} ${op} ${literal(v)}`);
+    return `(${clauses.join(join)})`;
+  }
+  /** `field ?= value` — at least one array element equals `value`. */
+  anyEq(value) {
+    return this.cmp("?=", value);
+  }
+  /** `field ?!= value` — at least one array element differs. */
+  anyNeq(value) {
+    return this.cmp("?!=", value);
+  }
+  /** `field ?~ value` — at least one array element contains `value`. */
+  anyContains(value) {
+    return this.cmp("?~", value);
+  }
+  /** `field ?!~ value` — at least one array element does not contain `value`. */
+  anyNotContains(value) {
+    return this.cmp("?!~", value);
+  }
+  /** `field ?> value` — at least one array element is greater. */
+  anyGt(value) {
+    return this.cmp("?>", value);
+  }
+  /** `field ?>= value` — at least one array element is greater or equal. */
+  anyGte(value) {
+    return this.cmp("?>=", value);
+  }
+  /** `field ?< value` — at least one array element is less. */
+  anyLt(value) {
+    return this.cmp("?<", value);
+  }
+  /** `field ?<= value` — at least one array element is less or equal. */
+  anyLte(value) {
+    return this.cmp("?<=", value);
+  }
+  cmp(op, value) {
+    return new FilterExpr(`${this.field} ${op} ${literal(value)}`);
+  }
+};
+
 // src/oauth2.ts
 var DEFAULT_POPUP_WIDTH = 500;
 var DEFAULT_POPUP_HEIGHT = 700;
@@ -708,14 +848,24 @@ function normalizeAction(event, rawAction) {
   if (event === "delete" || event === "record_delete") return "delete";
   return "update";
 }
+function pickFields(value, fields) {
+  if (!value || typeof value !== "object") return {};
+  const src = value;
+  const out = {};
+  for (const f of fields) {
+    if (f in src) out[f] = src[f];
+  }
+  return out;
+}
 var CollectionService = class _CollectionService {
   /** @internal */
-  constructor(http, collectionName, authStore, realtime, schema) {
+  constructor(http, collectionName, authStore, realtime, schema, schemaResolver) {
     this.http = http;
     this.collectionName = collectionName;
     this.authStore = authStore;
     this.realtime = realtime;
     this.schema = schema;
+    this.schemaResolver = schemaResolver;
   }
   encodeId(id) {
     return encodeURIComponent(id);
@@ -750,7 +900,8 @@ var CollectionService = class _CollectionService {
       this.collectionName,
       this.authStore,
       this.realtime,
-      this.schema
+      this.schema,
+      this.schemaResolver
     );
     derived.fieldsPreset = preset;
     if (this.schema && preset !== "*") {
@@ -813,20 +964,266 @@ var CollectionService = class _CollectionService {
       ])
     ].join(",");
   }
+  // ── Typed filter builder ──
+  /**
+   * Start a type-checked filter expression. The field name is suggested
+   * from the collection's key set and the value is checked against the
+   * field's type (when the service is typed). Values are escaped safely.
+   *
+   * ```ts
+   * const q = posts.where;
+   * await posts.getList(1, 20, {
+   *   filter: q("title").contains("x").and(q("published").eq(true)),
+   * });
+   * // → filter=(title ~ '%x%' && published = true)
+   *
+   * // PocketBase `?` array operators (multi-select / multi-relation):
+   * posts.getList(1, 20, { filter: q("tags").anyEq("news") });
+   * ```
+   *
+   * Chain `.and()` / `.or()` / `.not()` to compose. A `FilterExpr` can be
+   * passed anywhere a `filter` string is accepted. Relation dot-paths
+   * (`where("author.email")`) are supported by servers that compile
+   * relation dot-path filters, and `where("id").in(ids)` covers list
+   * membership without hand-written OR chains.
+   */
+  where(field) {
+    return new FilterBuilder(field);
+  }
+  /**
+   * Resolve a `filter` callback into a concrete string / {@link FilterExpr}.
+   * The callback receives this collection's typed `where` helper, so
+   * `filter: (w) => w("title").contains("x")` type-checks field names inline.
+   */
+  resolveFilter(filter) {
+    if (typeof filter !== "function") {
+      return filter;
+    }
+    return filter((field) => this.where(field));
+  }
+  /**
+   * Resolve the leading relation chain of an expand token against the
+   * (optionally schema-aware) collection graph.
+   *
+   * Walks `segments` from this collection: each segment that is a relation
+   * advances to its target collection. Stops at the first non-relation
+   * segment or when the target schema is unknown.
+   *
+   * @returns `depth` — how many leading segments are relations; and
+   * `canInspect` — whether the schema at `depth` is known (so the next
+   * segment can be classified as a field selection vs a nested relation).
+   */
+  resolveRelationChain(segments) {
+    let currentFields = this.schema?.fields;
+    if (!currentFields) return { depth: 0, canInspect: false };
+    for (let i = 0; i < segments.length; i++) {
+      const field = currentFields.find((f) => f.name === segments[i]);
+      if (!field || field.type !== "relation") {
+        return { depth: i, canInspect: true };
+      }
+      if (i === segments.length - 1) {
+        return { depth: segments.length, canInspect: true };
+      }
+      const target = this.resolveTargetCollection(field);
+      if (!target?.fields) {
+        return { depth: i + 1, canInspect: false };
+      }
+      currentFields = target.fields;
+    }
+    return { depth: segments.length, canInspect: true };
+  }
+  /** Follow a relation field to its target collection, if resolvable. */
+  resolveTargetCollection(field) {
+    const key = field.options?.collection ?? field.options?.collectionId ?? field.collectionId ?? void 0;
+    if (!key || !this.schemaResolver) return void 0;
+    return this.schemaResolver(String(key));
+  }
   /** Warn once when an expand field is not a relation (schema known). */
-  validateExpand(expand) {
-    if (!expand || !this.schema?.fields) return;
-    const relations = new Set(
-      this.schema.fields.filter((f) => f.type === "relation").map((f) => f.name)
+  warnNonRelation(name) {
+    console.warn(
+      `[lazypock] expand("${name}"): field is not a relation on collection "${this.collectionName}"`
     );
-    for (const f of expand.split(",")) {
-      const name = f.trim();
-      if (name && !relations.has(name)) {
-        console.warn(
-          `[lazypock] expand("${name}"): field is not a relation on collection "${this.collectionName}"`
-        );
+  }
+  /**
+   * Validate and normalise a caller's `expand` string.
+   *
+   * PocketBase only expands *relations*: a dotted token like `author.user`
+   * walks into the related record. Callers often use a dotted token to mean
+   * "only these fields of the expanded record" (`owner.name,owner.email`),
+   * which PocketBase silently drops. When the trailing segment is not a
+   * relation — resolved from the schema graph — the token is rewritten as a
+   * field selection:
+   *
+   * ```
+   * expand: 'owner.name,owner.email'
+   * → expand=owner&fields=<base>,expand.owner.name,expand.owner.email
+   * ```
+   *
+   * Tokens whose whole path is relations keep their existing nested-expand
+   * behaviour. Without a schema the two are indistinguishable, so a lone
+   * dotted token stays a nested expand (with a warning) while two or more
+   * dotted tokens sharing the same relation are treated as field selection.
+   */
+  normalizeExpand(expand) {
+    const narrow = /* @__PURE__ */ new Map();
+    if (!expand) return { fieldSelectors: [], narrow };
+    const tokens = expand.split(",").map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0) return { fieldSelectors: [], narrow };
+    const relations = this.schema?.fields ? new Set(
+      this.schema.fields.filter((f) => f.type === "relation").map((f) => f.name)
+    ) : void 0;
+    const parsed = [];
+    for (const token of tokens) {
+      const segments = token.split(".").filter(Boolean);
+      const base = segments[0] ?? token;
+      if (segments.length <= 1) {
+        if (relations && !relations.has(base)) {
+          this.warnNonRelation(base);
+        }
+        parsed.push({ token, base, segments, kind: "plain", depth: 0 });
+        continue;
+      }
+      if (!relations) {
+        parsed.push({ token, base, segments, kind: "unknown", depth: 1 });
+        continue;
+      }
+      const { depth, canInspect } = this.resolveRelationChain(segments);
+      if (depth === 0) {
+        this.warnNonRelation(base);
+        parsed.push({ token, base, segments, kind: "plain", depth: 0 });
+      } else if (depth === segments.length) {
+        parsed.push({ token, base, segments, kind: "nested", depth });
+      } else if (canInspect) {
+        parsed.push({ token, base, segments, kind: "narrow", depth });
+      } else {
+        parsed.push({ token, base, segments, kind: "unknown", depth });
+      }
+    }
+    const byBase = /* @__PURE__ */ new Map();
+    for (const t of parsed) {
+      const arr = byBase.get(t.base);
+      if (arr) arr.push(t);
+      else byBase.set(t.base, [t]);
+    }
+    for (const [base, group] of byBase) {
+      const unknowns = group.filter((t) => t.kind === "unknown");
+      if (unknowns.length === 0) continue;
+      const distinct = new Set(unknowns.map((t) => t.token));
+      const hasNarrow = group.some((t) => t.kind === "narrow");
+      if (!hasNarrow && distinct.size < 2) {
+        for (const t of unknowns) {
+          t.kind = "nested";
+          console.warn(
+            `[lazypock] expand("${t.token}"): treated as a nested relation. Pass types.schemas (or use fields=) to select fields of "${base}".`
+          );
+        }
+      } else {
+        for (const t of unknowns) t.kind = "narrow";
       }
     }
+    const expandParams = [];
+    const expandSeen = /* @__PURE__ */ new Set();
+    const fieldSelectors = [];
+    const selectorSeen = /* @__PURE__ */ new Set();
+    const pushParam = (p) => {
+      if (!expandSeen.has(p)) {
+        expandSeen.add(p);
+        expandParams.push(p);
+      }
+    };
+    const pushSelector = (s) => {
+      if (!selectorSeen.has(s)) {
+        selectorSeen.add(s);
+        fieldSelectors.push(s);
+      }
+    };
+    for (const t of parsed) {
+      if (t.kind === "plain") {
+        pushParam(t.token);
+        pushSelector(`expand.${t.token}`);
+      } else if (t.kind === "nested") {
+        for (let i = 1; i <= t.segments.length; i++) {
+          pushParam(t.segments.slice(0, i).join("."));
+        }
+        pushSelector(`expand.${t.segments[0]}`);
+      } else {
+        const depth = Math.max(1, t.depth);
+        const relationPath = t.segments.slice(0, depth).join(".");
+        pushParam(relationPath);
+        pushSelector(`expand.${t.segments.slice(0, depth + 1).join(".")}`);
+        if (t.segments.length === depth + 1) {
+          const base = t.segments[0];
+          const leaf = t.segments[depth];
+          const leaves = narrow.get(base) ?? [];
+          if (!leaves.includes(leaf)) leaves.push(leaf);
+          narrow.set(base, leaves);
+        }
+      }
+    }
+    return {
+      expand: expandParams.length > 0 ? expandParams.join(",") : void 0,
+      fieldSelectors,
+      narrow
+    };
+  }
+  /**
+   * Keep only the requested leaf fields on `record.expand.<relation>`.
+   *
+   * Mirrors PocketBase's server-side `fields=expand.<rel>.<field>` projection
+   * for servers that don't support it (the LazyPock server), so field
+   * selection behaves the same against both. A no-op when the server already
+   * narrowed the record. Multi-relations are narrowed element-wise.
+   */
+  applyExpandNarrowing(record, narrow) {
+    if (narrow.size === 0) return record;
+    const rec = record;
+    const expand = rec.expand;
+    if (!expand || typeof expand !== "object") return record;
+    const next = { ...expand };
+    for (const [relation, leaves] of narrow) {
+      const value = next[relation];
+      if (value === void 0 || value === null) continue;
+      next[relation] = Array.isArray(value) ? value.map((el) => pickFields(el, leaves)) : pickFields(value, leaves);
+    }
+    return { ...rec, expand: next };
+  }
+  /**
+   * Merge the expand-preserving selectors into the base field projection.
+   *
+   * Both servers are kept happy at once:
+   * - PocketBase drops the whole `expand` payload unless an `expand.<key>`
+   *   entry is present in `fields`;
+   * - the LazyPock server projects first (strict, top-level only) and then
+   *   expands, so the relation *field* itself must be present in `fields`.
+   *
+   * We therefore add both the relation field (`cate`) and the
+   * `expand.<key>` entry. When no projection is active, no `fields` param is
+   * sent at all — a value like `*` plus other tokens is not a wildcard on
+   * the LazyPock server (it is a strict take, yielding empty records) and
+   * the server keeps `expand` by default when `fields` is absent.
+   */
+  mergeExpandFields(base, info) {
+    if (info.fieldSelectors.length === 0) return base;
+    if (base === void 0) return void 0;
+    const parts = base.split(",").map((f) => f.trim()).filter(Boolean);
+    const seen = new Set(parts);
+    const push = (value) => {
+      if (seen.has(value)) return;
+      seen.add(value);
+      parts.push(value);
+    };
+    const fullKeys = /* @__PURE__ */ new Set();
+    for (const selector of info.fieldSelectors) {
+      const seg = selector.split(".");
+      if (seg.length === 2) fullKeys.add(seg[1]);
+    }
+    for (const selector of info.fieldSelectors) {
+      const seg = selector.split(".");
+      if (seg.length > 2 && fullKeys.has(seg[1])) continue;
+      if (seg.length >= 2) push(seg[1]);
+      push(selector);
+    }
+    return parts.join(",");
   }
   /**
    * Fetch a paginated list of records (PocketBase `getList`).
@@ -835,7 +1232,7 @@ var CollectionService = class _CollectionService {
    * @param perPage Records per page (default 30).
    * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
    */
-  getList(page = 1, perPage = 30, options) {
+  async getList(page = 1, perPage = 30, options) {
     const {
       requestKey,
       autoCancel,
@@ -847,12 +1244,29 @@ var CollectionService = class _CollectionService {
       params,
       ...queryParams
     } = options ?? {};
-    const fields = this.effectiveFields(queryParams.fields);
-    if (fields !== void 0 && queryParams.fields === void 0) {
-      queryParams.fields = fields;
+    if (Array.isArray(queryParams.sort)) {
+      queryParams.sort = queryParams.sort.join(",");
     }
-    if (typeof queryParams.expand === "string") {
-      this.validateExpand(queryParams.expand);
+    if (Array.isArray(queryParams.expand)) {
+      queryParams.expand = queryParams.expand.join(",");
+    }
+    if (typeof queryParams.filter === "function") {
+      queryParams.filter = this.resolveFilter(
+        queryParams.filter
+      );
+    }
+    const expandInfo = this.normalizeExpand(
+      typeof queryParams.expand === "string" ? queryParams.expand : void 0
+    );
+    if (expandInfo.expand !== void 0) {
+      queryParams.expand = expandInfo.expand;
+    }
+    const fields = this.mergeExpandFields(
+      this.effectiveFields(queryParams.fields),
+      expandInfo
+    );
+    if (fields !== void 0) {
+      queryParams.fields = fields;
     }
     const qs = new URLSearchParams(
       Object.fromEntries(
@@ -863,19 +1277,22 @@ var CollectionService = class _CollectionService {
         }).map(([k, v]) => [k, String(v)])
       )
     ).toString();
-    return this.http.get(
-      "/" + this.encodeId(this.collectionName) + "?" + qs,
-      {
-        requestKey,
-        autoCancel,
-        cancelKey,
-        fetch,
-        headers,
-        signal,
-        singleFlight,
-        params
-      }
-    );
+    const result = await this.http.get("/" + this.encodeId(this.collectionName) + "?" + qs, {
+      requestKey,
+      autoCancel,
+      cancelKey,
+      fetch,
+      headers,
+      signal,
+      singleFlight,
+      params
+    });
+    if (result && expandInfo.narrow.size > 0) {
+      result.items = result.items.map(
+        (item) => this.applyExpandNarrowing(item, expandInfo.narrow)
+      );
+    }
+    return result;
   }
   /**
    * Fetch all records at once (auto-paginates). Mirrors PocketBase's
@@ -885,6 +1302,9 @@ var CollectionService = class _CollectionService {
    */
   async getFullList(options) {
     const { batch = 1e3, ...rest } = options ?? {};
+    if (typeof rest.filter === "function") {
+      rest.filter = this.resolveFilter(rest.filter);
+    }
     const effectiveKey = typeof rest.requestKey === "string" ? rest.requestKey : `getFullList:${this.collectionName}:${stableStringify(rest)}`;
     const items = [];
     let page = 1;
@@ -923,19 +1343,32 @@ var CollectionService = class _CollectionService {
    * @param id Record ID.
    * @param options Optional request options.
    */
-  getOne(id, options) {
-    const fields = this.effectiveFields(options?.fields);
-    if (typeof options?.expand === "string") {
-      this.validateExpand(options.expand);
-    }
+  async getOne(id, options) {
+    let rawExpand;
+    if (Array.isArray(options?.expand)) {
+      rawExpand = options.expand.join(",");
+    } else if (typeof options?.expand === "string") {
+      rawExpand = options.expand;
+    }
+    const expandInfo = this.normalizeExpand(rawExpand);
+    const fields = this.mergeExpandFields(
+      this.effectiveFields(options?.fields),
+      expandInfo
+    );
     const qs = new URLSearchParams();
     if (fields !== void 0) qs.set("fields", fields);
-    if (typeof options?.expand === "string") qs.set("expand", options.expand);
+    if (rawExpand !== void 0) {
+      qs.set("expand", expandInfo.expand ?? rawExpand);
+    }
     const qsStr = qs.toString();
-    return this.http.get(
+    const record = await this.http.get(
       "/" + this.encodeId(this.collectionName) + "/" + this.encodeId(id) + (qsStr ? "?" + qsStr : ""),
       options
     );
+    if (record && expandInfo.narrow.size > 0) {
+      return this.applyExpandNarrowing(record, expandInfo.narrow);
+    }
+    return record;
   }
   /**
    * Create a new record.
@@ -1019,7 +1452,8 @@ var CollectionService = class _CollectionService {
       this.collectionName,
       this.authStore,
       this.realtime,
-      schema
+      schema,
+      this.schemaResolver
     );
     derived.fieldsPreset = this.fieldsPreset;
     return derived;
@@ -2097,6 +2531,10 @@ var LazypockClient = class {
       this.schemaByName = new Map(
         options.types.schemas.map((s) => [s.name, s])
       );
+      this.schemaById = /* @__PURE__ */ new Map();
+      for (const s of options.types.schemas) {
+        if (s.id) this.schemaById.set(String(s.id), s);
+      }
     }
   }
   /**
@@ -2119,7 +2557,10 @@ var LazypockClient = class {
         this.authStore,
         this.realtime,
         // Prefer the explicit schema, then the client-level `types.schemas`.
-        schema ?? this.schemaByName?.get(name)
+        schema ?? this.schemaByName?.get(name),
+        // Let the service follow relation fields into other collections
+        // (expand field selection vs nested-relation expansion).
+        (key) => this.schemaByName?.get(key) ?? this.schemaById?.get(key)
       );
       this.collectionCache.set(name, svc);
     }
@@ -2315,6 +2756,8 @@ function createClient(options) {
   CollectionService,
   CollectionsService,
   FilesService,
+  FilterBuilder,
+  FilterExpr,
   HttpClient,
   LazypockClient,
   RealtimeService,