lazypock 0.10.0 → 0.10.2

package/dist/index.d.cts

@@ -105,16 +105,106 @@ type FieldKey<T> = Extract<keyof T, string> extends never ? string : Extract<key
 type FilterOp = "=" | "!=" | "~" | "!~" | ">" | ">=" | "<" | "<=";
 /** Optional whitespace around a filter operator (`project=x` and `project = x` both compile). */
 type FilterWs = "" | " ";
+/** Trim one-or-more leading/trailing spaces off a string literal. */
+type Trim<S extends string> = S extends ` ${infer R}` ? Trim<R> : S extends `${infer L} ` ? Trim<L> : S;
+/** `never` when the string contains a single-quote. */
+type NoQuote<S extends string> = S extends `${string}'${string}` ? never : S;
+/** `never` when the string contains a double-quote. */
+type NoDQuote<S extends string> = S extends `${string}"${string}` ? never : S;
+/** Single decimal digits — used to consume numeric values char-by-char. */
+type Digits = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /**
- * A filterable field: a top-level key, or a dot-path into a relation
- * (`author.email = 'x'`).
+ * Consume a leading number (digits plus an optional decimal part) and
+ * return the remainder. `\`${number}\`` is NOT used in template positions:
+ * it matches a single digit, leaving `"0"` behind for `"10"`.
  */
-type FilterField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+type ConsumeNum<S extends string> = S extends `${infer C}${infer R}` ? C extends Digits ? ConsumeNum<R> : C extends "." ? R extends `${Digits}${string}` ? ConsumeNum<R> : S : S : S;
 /**
- * One `field op value` clause. Spaces around the operator are optional
- * (`project=x` / `project = x`) — the backend treats them the same.
+ * Consume chars up to (not including) the first banned char and return the
+ * remainder. Bounds dot-paths so a path can't swallow a following clause.
  */
-type FilterClause<T> = `${FilterField<T>}${FilterWs}${FilterOp}${FilterWs}${string}`;
+type ConsumeUntil<S extends string, Ban extends string> = S extends `${infer C}${infer R}` ? C extends Ban ? S : ConsumeUntil<R, Ban> : S;
+/** Chars that terminate a relation dot-path. */
+type PathBan = " " | "&" | "|" | "(" | ")" | "'" | "\"";
+/**
+ * A single expandable token: a top-level key, or a dot-path into a relation
+ * (`author.user.profile`). Only the first segment is validated — nested
+ * segments reference fields of the *target* collection, which `T` doesn't
+ * describe.
+ */
+type ExpandField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+/**
+ * Validate every comma-separated expand token; returns the original literal
+ * `O` when all tokens are valid, `never` otherwise. Spaces around commas are
+ * tolerated (the runtime trims tokens too).
+ */
+type ValidExpand<T, E extends string, O extends string = E> = string extends FieldKey<T> ? O : E extends `${infer Head},${infer Tail}` ? Trim<Head> extends ExpandField<T> ? ValidExpand<T, Trim<Tail>, O> : never : Trim<E> extends ExpandField<T> ? O : never;
+/**
+ * Type-checked expand string: comma-separated relation field names,
+ * including nested dot-paths (e.g. `"author"`, `"author,category"`,
+ * `"author.user.profile"`). **Every** comma-separated token is validated —
+ * `expand: "author, nope"` is a compile error, not just the first token.
+ * Non-relation fields are warned about at runtime when a schema is
+ * available.
+ */
+type ExpandString<T, E extends string = never> = E & (E extends ValidExpand<T, E, E> ? E : never);
+/** A single `[+|-]field` sort token. */
+type SortField<T> = `${"" | "-" | "+"}${FieldKey<T>}`;
+/**
+ * Validate every comma-separated sort token; returns the original literal
+ * `O` when all tokens are valid, `never` otherwise.
+ */
+type ValidSort<T, E extends string, O extends string = E> = string extends FieldKey<T> ? O : E extends `${infer Head},${infer Tail}` ? Trim<Head> extends SortField<T> ? ValidSort<T, Trim<Tail>, O> : never : Trim<E> extends SortField<T> ? O : never;
+/**
+ * Type-checked sort string: `field`, `-field` (desc), `+field`, or
+ * comma-separated combinations (e.g. `"-created,title"`). **Every** token is
+ * validated — `sort: "title, nope"` is a compile error.
+ */
+type SortString<T, E extends string = never> = E & (E extends ValidSort<T, E, E> ? E : never);
+/**
+ * A string value with no quotes, `&&`/`||`, or parens — the "bare" fallback
+ * for filter values (numbers, `true`/`false`/`null`, unquoted text).
+ * Applied against the *same* literal (`S extends SimpleVal<S>`) so the
+ * banned-char checks run on the concrete substring, not on the abstract
+ * `string` type.
+ */
+type SimpleVal<S extends string> = (S extends `${string}'${string}` ? never : S) & (S extends `${string}"${string}` ? never : S) & (S extends `${string}&&${string}` ? never : S) & (S extends `${string}||${string}` ? never : S) & (S extends `${string}(${string}` ? never : S) & (S extends `${string})${string}` ? never : S);
+/**
+ * Field-reference value (`title = author` / `title = author.email`): a
+ * top-level key, optionally followed by a bounded dot-path. Returns the
+ * remainder after the value.
+ */
+type FFieldRef<T, S extends string> = S extends `${FieldKey<T>}${infer R}` ? R extends `.${infer Rest}` ? ConsumeUntil<Rest, PathBan> : R : never;
+/**
+ * Consume one filter value (quoted string, number, boolean/null, field
+ * reference, or bare text) and return the remainder — the input left for the
+ * `&&`/`||`/`)`/end checks upstream.
+ */
+type FValue<T, S extends string> = (S extends `'${infer V}'${infer R}` ? (V extends NoQuote<V> ? R : never) : never) | (S extends `"${infer V}"${infer R}` ? (V extends NoDQuote<V> ? R : never) : never) | (S extends `${"true" | "false" | "null"}${infer R}` ? R : never) | (S extends `-${infer Rest}` ? Rest extends `${Digits}${string}` ? ConsumeNum<Rest> : never : S extends `${Digits}${string}` ? ConsumeNum<S> : never) | FFieldRef<T, S> | (S extends SimpleVal<S> ? "" : never);
+/**
+ * Parse one `field op value` clause — either a plain top-level field or a
+ * bounded relation dot-path — and return the remainder. Spaces around the
+ * operator are optional (`project=x` / `project = x`).
+ */
+type FClause<T, S extends string> = S extends `${FieldKey<T>}${infer R}` ? R extends `${FilterWs}${FilterOp}${FilterWs}${infer R2}` ? FValue<T, Trim<R2>> : R extends `.${infer Rest}` ? ConsumeUntil<Rest, PathBan> extends infer R2 ? R2 extends `${FilterWs}${FilterOp}${FilterWs}${infer R3}` ? FValue<T, Trim<R3>> : never : never : never : never;
+/** A clause or a parenthesised group; parens must balance and close. */
+type FAtom<T, S extends string> = FClause<T, S> | (S extends `(${infer Inner}` ? FOr<T, Inner> extends infer R ? R extends `)${infer Tail}` ? Tail : never : never : never);
+/** Optional `!` negation in front of an atom. */
+type FNot<T, S extends string> = S extends `!${infer Tail}` ? FAtom<T, Tail> : FAtom<T, S>;
+/**
+ * One or more atoms joined by `&&`. Returns `never` on parse failure (a
+ * failed atom must not masquerade as an empty remainder — `never extends ""`
+ * is true), the empty string on success, or the unconsumed remainder.
+ */
+type FAnd<T, S extends string> = FNot<T, S> extends infer R ? [R] extends [never] ? never : R extends "" ? "" : R extends `${FilterWs}&&${FilterWs}${infer Tail}` ? FAnd<T, Tail> : R : never;
+/** One or more `&&`-chains joined by `||` — the top-level expression. */
+type FOr<T, S extends string> = FAnd<T, S> extends infer R ? [R] extends [never] ? never : R extends "" ? "" : R extends `${FilterWs}||${FilterWs}${infer Tail}` ? FOr<T, Tail> : R : never;
+/**
+ * Validate a full filter expression: the parser must consume the entire
+ * (trimmed) string. Compares the *literal* against the parse result rather
+ * than `extends ""` so a `never` parse failure can't satisfy the check.
+ */
+type ValidFilter<T, F extends string, O extends string = F> = string extends FieldKey<T> ? O : "" extends FOr<T, Trim<F>> ? O : never;
 /**
  * Type-checked filter expression (PocketBase syntax).
  *
@@ -125,52 +215,62 @@ type FilterClause<T> = `${FilterField<T>}${FilterWs}${FilterOp}${FilterWs}${stri
  * getList(1, 20, { filter: "author.email = 'x'" })    // relation dot-path
  * ```
  *
- * The expression must start with a valid field name — optionally preceded by
- * `!` / `(` / `!(` — followed by a valid operator; the rest (values,
- * `&&`/`||`, `!`, parens) is free-form. Field names and operators are
- * suggested by the editor as you type.
- */
-type FilterString<T> = `${FilterClause<T>}${string}` | `${"!" | "(" | "!("}${FilterClause<T>}${string}`;
-/** A single `[+|-]field` sort token. */
-type SortField<T> = `${"" | "-" | "+"}${FieldKey<T>}`;
-/**
- * Type-checked sort string: `field`, `-field` (desc), `+field`, or
- * comma-separated combinations (e.g. `"-created,title"`).
+ * **Every** `field op value` clause is validated — the field name, the
+ * operator, and the clause structure (`&&`, `||`, `!`, parens, and nested
+ * groups all typecheck). Quoted values may contain `&&`/`||` (e.g.
+ * `title ~ 'a && b'`); bare unquoted values are bounded so they can't hide a
+ * following clause. When the expression is a plain dynamic `string` (e.g.
+ * `filter: \`title=${search}\``), the guard falls back to accepting it
+ * verbatim — the server decides at runtime.
  */
-type SortString<T> = SortField<T> | `${SortField<T>},${string}`;
+type FilterString<T, F extends string = never> = F & (F extends ValidFilter<T, F, F> ? F : string extends F ? F : never);
 /**
- * Type-checked expand string: comma-separated relation field names,
- * including nested dot-paths (e.g. `"author"`, `"author,category"`,
- * `"author.user.profile"`). Non-relation fields are warned about at
- * runtime when a schema is available.
+ * First segment of a single expand token (`"author.user"` → `"author"`) —
+ * the key PocketBase uses on the expanded record.
  */
-type ExpandField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+type TopExpandKey<S extends string> = S extends `${infer A}.${string}` ? A : S;
+/** Top-level keys of a comma-separated expand literal (`"a,b"` → `"a" | "b"`). */
+type ExpandKeys<S extends string> = S extends "" ? never : S extends `${infer H},${infer T}` ? TopExpandKey<H> | ExpandKeys<T> : TopExpandKey<S>;
 /**
- * Type-checked expand string: comma-separated relation field names,
- * including nested dot-paths (e.g. `"author"`, `"author,category"`,
- * `"author.user.profile"`).
+ * The `expand` property attached to records when `expand` is used. Keys are
+ * parsed from the caller's expand literal (dot-paths collapse to their first
+ * segment), so `record.expand.user` typechecks and the nested record is
+ * `unknown` (its shape belongs to the target collection). Falls back to
+ * `Record<string, unknown>` when the expand value is dynamic or absent.
  */
-type ExpandString<T> = ExpandField<T> | `${ExpandField<T>},${string}`;
+type ExpandObj<E extends string> = [
+    E
+] extends [never] ? Record<string, unknown> : [
+    string
+] extends [E] ? Record<string, unknown> : Partial<Record<ExpandKeys<E>, unknown>>;
 /**
  * Query options for list/read operations, typed against a record shape `T`.
  *
  * `filter`, `sort`, `expand` and `fields` are recognized; any other key is
  * passed through as a raw query parameter (PocketBase-compatible).
+ *
+ * The `E`/`S`/`F` generics are inferred from the caller's literals; the
+ * {@link CollectionService} methods constrain them with the validated
+ * {@link ExpandString} / {@link SortString} / {@link FilterString} guards.
+ */
+/**
+ * `_T` is kept for backward compatibility (`ListOptions<Post>`) but the
+ * per-field validation now runs through the `E`/`S`/`F` generics.
  */
-interface ListOptions<T = ApiRecord> {
+interface ListOptions<_T = ApiRecord, E extends string = never, S extends string = never, F extends string = never> {
     /**
      * PocketBase filter expression. Field names + operators are type-checked
      * when `T` is a concrete shape.
      */
-    filter?: FilterString<T>;
+    filter?: FilterString<_T, F>;
     /**
      * Sort field(s): `field`, `-field` (descending), comma-separated.
      */
-    sort?: SortString<T>;
+    sort?: SortString<_T, S>;
     /**
      * Comma-separated relation field names to expand.
      */
-    expand?: ExpandString<T>;
+    expand?: ExpandString<_T, E>;
     /**
      * Explicit field projection (overrides {@link CollectionService.select}).
      */
@@ -183,9 +283,9 @@ interface ListOptions<T = ApiRecord> {
 /**
  * Options for single-record reads (`getOne`): expand + explicit fields.
  */
-interface ReadOptions<T = ApiRecord> {
+interface ReadOptions<_T = ApiRecord, E extends string = never> {
     /** Comma-separated relation field names to expand. */
-    expand?: ExpandString<T>;
+    expand?: ExpandString<_T, E>;
     /** Explicit field projection (overrides {@link CollectionService.select}). */
     fields?: string;
 }
@@ -534,8 +634,14 @@ interface RealtimeSubscribeOptions {
  * Get an instance via {@link LazypockClient.collection}.
  *
  * @typeParam T — The record shape for this collection. Defaults to {@link ApiRecord}.
+ * @typeParam TData — Write-only create/update payload shape (defaults to `never`,
+ * which falls back to `T`-derived create data).
+ * @typeParam TFields — The key set accepted by `filter`/`sort`/`expand`/`select`.
+ * Defaults to `T`. The codegen client binds a *QueryFields type that includes
+ * hidden fields — excluded from the read model but still expandable/filterable
+ * at runtime — so `expand: "hiddenRelation"` typechecks.
  */
-declare class CollectionService<T = ApiRecord, TData = never> {
+declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
     private http;
     private collectionName;
     private authStore?;
@@ -574,7 +680,7 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * `fields` param — the server returns every non-password field.
      * Pass `select("*")` to restore the default after a projection.
      */
-    select<K extends FieldKey<T> | "*">(...fields: K[]): CollectionService<T, TData>;
+    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields>;
     /**
      * Fields to send with reads:
      * 1. explicit `options.fields` (caller wins)
@@ -607,27 +713,35 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * @param perPage Records per page (default 30).
      * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
      */
-    getList<T2 = T>(page?: number, perPage?: number, options?: ListOptions<T> & RequestOptions): Promise<ListResult<T2> | null>;
+    getList<T2 = T, E extends string = never, S extends string = never, F extends string = never>(page?: number, perPage?: number, options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<ListResult<T2 & {
+        expand?: ExpandObj<E>;
+    }> | null>;
     /**
      * Fetch all records at once (auto-paginates). Mirrors PocketBase's
      * `pb.collection(name).getFullList()`.
      *
      * @param options Query params (`sort`, `filter`, `batch`, etc.) + request options.
      */
-    getFullList<T2 = T>(options?: ListOptions<T> & RequestOptions): Promise<Array<T2>>;
+    getFullList<T2 = T, E extends string = never, S extends string = never, F extends string = never>(options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<Array<T2 & {
+        expand?: ExpandObj<E>;
+    }>>;
     /**
      * Fetch the first record matching a filter (PocketBase `getFirstListItem`).
      *
      * @param filter Filter expression (e.g. `title = 'x'`).
      * @param options Optional request options.
      */
-    getFirstListItem<T2 = T>(filter: FilterString<T>, options?: ListOptions<T> & RequestOptions): Promise<T2 | null>;
+    getFirstListItem<T2 = T, F extends string = never, E extends string = never, S extends string = never>(filter: FilterString<TFields, F>, options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<(T2 & {
+        expand?: ExpandObj<E>;
+    }) | null>;
     /**
      * Get a single record by ID.
      * @param id Record ID.
      * @param options Optional request options.
      */
-    getOne(id: string, options?: ReadOptions<T> & RequestOptions): Promise<T | null>;
+    getOne<E extends string = never>(id: string, options?: ReadOptions<TFields, E> & RequestOptions): Promise<(T & {
+        expand?: ExpandObj<E>;
+    }) | null>;
     /**
      * Create a new record.
      * @param data Record fields. When `T` is a concrete shape (e.g. a generated
@@ -680,7 +794,7 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * `types.schemas`). Enables schema-aware defaults: hidden fields are
      * excluded from responses, select/expand are validated.
      */
-    withSchema(schema: CollectionSchema): CollectionService<T, TData>;
+    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields>;
     /**
      * Subscribe to realtime changes for this collection.
      * The event's `action` is one of `"create" | "update" | "delete"` and the

package/dist/index.d.ts

@@ -105,16 +105,106 @@ type FieldKey<T> = Extract<keyof T, string> extends never ? string : Extract<key
 type FilterOp = "=" | "!=" | "~" | "!~" | ">" | ">=" | "<" | "<=";
 /** Optional whitespace around a filter operator (`project=x` and `project = x` both compile). */
 type FilterWs = "" | " ";
+/** Trim one-or-more leading/trailing spaces off a string literal. */
+type Trim<S extends string> = S extends ` ${infer R}` ? Trim<R> : S extends `${infer L} ` ? Trim<L> : S;
+/** `never` when the string contains a single-quote. */
+type NoQuote<S extends string> = S extends `${string}'${string}` ? never : S;
+/** `never` when the string contains a double-quote. */
+type NoDQuote<S extends string> = S extends `${string}"${string}` ? never : S;
+/** Single decimal digits — used to consume numeric values char-by-char. */
+type Digits = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /**
- * A filterable field: a top-level key, or a dot-path into a relation
- * (`author.email = 'x'`).
+ * Consume a leading number (digits plus an optional decimal part) and
+ * return the remainder. `\`${number}\`` is NOT used in template positions:
+ * it matches a single digit, leaving `"0"` behind for `"10"`.
  */
-type FilterField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+type ConsumeNum<S extends string> = S extends `${infer C}${infer R}` ? C extends Digits ? ConsumeNum<R> : C extends "." ? R extends `${Digits}${string}` ? ConsumeNum<R> : S : S : S;
 /**
- * One `field op value` clause. Spaces around the operator are optional
- * (`project=x` / `project = x`) — the backend treats them the same.
+ * Consume chars up to (not including) the first banned char and return the
+ * remainder. Bounds dot-paths so a path can't swallow a following clause.
  */
-type FilterClause<T> = `${FilterField<T>}${FilterWs}${FilterOp}${FilterWs}${string}`;
+type ConsumeUntil<S extends string, Ban extends string> = S extends `${infer C}${infer R}` ? C extends Ban ? S : ConsumeUntil<R, Ban> : S;
+/** Chars that terminate a relation dot-path. */
+type PathBan = " " | "&" | "|" | "(" | ")" | "'" | "\"";
+/**
+ * A single expandable token: a top-level key, or a dot-path into a relation
+ * (`author.user.profile`). Only the first segment is validated — nested
+ * segments reference fields of the *target* collection, which `T` doesn't
+ * describe.
+ */
+type ExpandField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+/**
+ * Validate every comma-separated expand token; returns the original literal
+ * `O` when all tokens are valid, `never` otherwise. Spaces around commas are
+ * tolerated (the runtime trims tokens too).
+ */
+type ValidExpand<T, E extends string, O extends string = E> = string extends FieldKey<T> ? O : E extends `${infer Head},${infer Tail}` ? Trim<Head> extends ExpandField<T> ? ValidExpand<T, Trim<Tail>, O> : never : Trim<E> extends ExpandField<T> ? O : never;
+/**
+ * Type-checked expand string: comma-separated relation field names,
+ * including nested dot-paths (e.g. `"author"`, `"author,category"`,
+ * `"author.user.profile"`). **Every** comma-separated token is validated —
+ * `expand: "author, nope"` is a compile error, not just the first token.
+ * Non-relation fields are warned about at runtime when a schema is
+ * available.
+ */
+type ExpandString<T, E extends string = never> = E & (E extends ValidExpand<T, E, E> ? E : never);
+/** A single `[+|-]field` sort token. */
+type SortField<T> = `${"" | "-" | "+"}${FieldKey<T>}`;
+/**
+ * Validate every comma-separated sort token; returns the original literal
+ * `O` when all tokens are valid, `never` otherwise.
+ */
+type ValidSort<T, E extends string, O extends string = E> = string extends FieldKey<T> ? O : E extends `${infer Head},${infer Tail}` ? Trim<Head> extends SortField<T> ? ValidSort<T, Trim<Tail>, O> : never : Trim<E> extends SortField<T> ? O : never;
+/**
+ * Type-checked sort string: `field`, `-field` (desc), `+field`, or
+ * comma-separated combinations (e.g. `"-created,title"`). **Every** token is
+ * validated — `sort: "title, nope"` is a compile error.
+ */
+type SortString<T, E extends string = never> = E & (E extends ValidSort<T, E, E> ? E : never);
+/**
+ * A string value with no quotes, `&&`/`||`, or parens — the "bare" fallback
+ * for filter values (numbers, `true`/`false`/`null`, unquoted text).
+ * Applied against the *same* literal (`S extends SimpleVal<S>`) so the
+ * banned-char checks run on the concrete substring, not on the abstract
+ * `string` type.
+ */
+type SimpleVal<S extends string> = (S extends `${string}'${string}` ? never : S) & (S extends `${string}"${string}` ? never : S) & (S extends `${string}&&${string}` ? never : S) & (S extends `${string}||${string}` ? never : S) & (S extends `${string}(${string}` ? never : S) & (S extends `${string})${string}` ? never : S);
+/**
+ * Field-reference value (`title = author` / `title = author.email`): a
+ * top-level key, optionally followed by a bounded dot-path. Returns the
+ * remainder after the value.
+ */
+type FFieldRef<T, S extends string> = S extends `${FieldKey<T>}${infer R}` ? R extends `.${infer Rest}` ? ConsumeUntil<Rest, PathBan> : R : never;
+/**
+ * Consume one filter value (quoted string, number, boolean/null, field
+ * reference, or bare text) and return the remainder — the input left for the
+ * `&&`/`||`/`)`/end checks upstream.
+ */
+type FValue<T, S extends string> = (S extends `'${infer V}'${infer R}` ? (V extends NoQuote<V> ? R : never) : never) | (S extends `"${infer V}"${infer R}` ? (V extends NoDQuote<V> ? R : never) : never) | (S extends `${"true" | "false" | "null"}${infer R}` ? R : never) | (S extends `-${infer Rest}` ? Rest extends `${Digits}${string}` ? ConsumeNum<Rest> : never : S extends `${Digits}${string}` ? ConsumeNum<S> : never) | FFieldRef<T, S> | (S extends SimpleVal<S> ? "" : never);
+/**
+ * Parse one `field op value` clause — either a plain top-level field or a
+ * bounded relation dot-path — and return the remainder. Spaces around the
+ * operator are optional (`project=x` / `project = x`).
+ */
+type FClause<T, S extends string> = S extends `${FieldKey<T>}${infer R}` ? R extends `${FilterWs}${FilterOp}${FilterWs}${infer R2}` ? FValue<T, Trim<R2>> : R extends `.${infer Rest}` ? ConsumeUntil<Rest, PathBan> extends infer R2 ? R2 extends `${FilterWs}${FilterOp}${FilterWs}${infer R3}` ? FValue<T, Trim<R3>> : never : never : never : never;
+/** A clause or a parenthesised group; parens must balance and close. */
+type FAtom<T, S extends string> = FClause<T, S> | (S extends `(${infer Inner}` ? FOr<T, Inner> extends infer R ? R extends `)${infer Tail}` ? Tail : never : never : never);
+/** Optional `!` negation in front of an atom. */
+type FNot<T, S extends string> = S extends `!${infer Tail}` ? FAtom<T, Tail> : FAtom<T, S>;
+/**
+ * One or more atoms joined by `&&`. Returns `never` on parse failure (a
+ * failed atom must not masquerade as an empty remainder — `never extends ""`
+ * is true), the empty string on success, or the unconsumed remainder.
+ */
+type FAnd<T, S extends string> = FNot<T, S> extends infer R ? [R] extends [never] ? never : R extends "" ? "" : R extends `${FilterWs}&&${FilterWs}${infer Tail}` ? FAnd<T, Tail> : R : never;
+/** One or more `&&`-chains joined by `||` — the top-level expression. */
+type FOr<T, S extends string> = FAnd<T, S> extends infer R ? [R] extends [never] ? never : R extends "" ? "" : R extends `${FilterWs}||${FilterWs}${infer Tail}` ? FOr<T, Tail> : R : never;
+/**
+ * Validate a full filter expression: the parser must consume the entire
+ * (trimmed) string. Compares the *literal* against the parse result rather
+ * than `extends ""` so a `never` parse failure can't satisfy the check.
+ */
+type ValidFilter<T, F extends string, O extends string = F> = string extends FieldKey<T> ? O : "" extends FOr<T, Trim<F>> ? O : never;
 /**
  * Type-checked filter expression (PocketBase syntax).
  *
@@ -125,52 +215,62 @@ type FilterClause<T> = `${FilterField<T>}${FilterWs}${FilterOp}${FilterWs}${stri
  * getList(1, 20, { filter: "author.email = 'x'" })    // relation dot-path
  * ```
  *
- * The expression must start with a valid field name — optionally preceded by
- * `!` / `(` / `!(` — followed by a valid operator; the rest (values,
- * `&&`/`||`, `!`, parens) is free-form. Field names and operators are
- * suggested by the editor as you type.
- */
-type FilterString<T> = `${FilterClause<T>}${string}` | `${"!" | "(" | "!("}${FilterClause<T>}${string}`;
-/** A single `[+|-]field` sort token. */
-type SortField<T> = `${"" | "-" | "+"}${FieldKey<T>}`;
-/**
- * Type-checked sort string: `field`, `-field` (desc), `+field`, or
- * comma-separated combinations (e.g. `"-created,title"`).
+ * **Every** `field op value` clause is validated — the field name, the
+ * operator, and the clause structure (`&&`, `||`, `!`, parens, and nested
+ * groups all typecheck). Quoted values may contain `&&`/`||` (e.g.
+ * `title ~ 'a && b'`); bare unquoted values are bounded so they can't hide a
+ * following clause. When the expression is a plain dynamic `string` (e.g.
+ * `filter: \`title=${search}\``), the guard falls back to accepting it
+ * verbatim — the server decides at runtime.
  */
-type SortString<T> = SortField<T> | `${SortField<T>},${string}`;
+type FilterString<T, F extends string = never> = F & (F extends ValidFilter<T, F, F> ? F : string extends F ? F : never);
 /**
- * Type-checked expand string: comma-separated relation field names,
- * including nested dot-paths (e.g. `"author"`, `"author,category"`,
- * `"author.user.profile"`). Non-relation fields are warned about at
- * runtime when a schema is available.
+ * First segment of a single expand token (`"author.user"` → `"author"`) —
+ * the key PocketBase uses on the expanded record.
  */
-type ExpandField<T> = `${FieldKey<T>}${"" | `.${string}`}`;
+type TopExpandKey<S extends string> = S extends `${infer A}.${string}` ? A : S;
+/** Top-level keys of a comma-separated expand literal (`"a,b"` → `"a" | "b"`). */
+type ExpandKeys<S extends string> = S extends "" ? never : S extends `${infer H},${infer T}` ? TopExpandKey<H> | ExpandKeys<T> : TopExpandKey<S>;
 /**
- * Type-checked expand string: comma-separated relation field names,
- * including nested dot-paths (e.g. `"author"`, `"author,category"`,
- * `"author.user.profile"`).
+ * The `expand` property attached to records when `expand` is used. Keys are
+ * parsed from the caller's expand literal (dot-paths collapse to their first
+ * segment), so `record.expand.user` typechecks and the nested record is
+ * `unknown` (its shape belongs to the target collection). Falls back to
+ * `Record<string, unknown>` when the expand value is dynamic or absent.
  */
-type ExpandString<T> = ExpandField<T> | `${ExpandField<T>},${string}`;
+type ExpandObj<E extends string> = [
+    E
+] extends [never] ? Record<string, unknown> : [
+    string
+] extends [E] ? Record<string, unknown> : Partial<Record<ExpandKeys<E>, unknown>>;
 /**
  * Query options for list/read operations, typed against a record shape `T`.
  *
  * `filter`, `sort`, `expand` and `fields` are recognized; any other key is
  * passed through as a raw query parameter (PocketBase-compatible).
+ *
+ * The `E`/`S`/`F` generics are inferred from the caller's literals; the
+ * {@link CollectionService} methods constrain them with the validated
+ * {@link ExpandString} / {@link SortString} / {@link FilterString} guards.
+ */
+/**
+ * `_T` is kept for backward compatibility (`ListOptions<Post>`) but the
+ * per-field validation now runs through the `E`/`S`/`F` generics.
  */
-interface ListOptions<T = ApiRecord> {
+interface ListOptions<_T = ApiRecord, E extends string = never, S extends string = never, F extends string = never> {
     /**
      * PocketBase filter expression. Field names + operators are type-checked
      * when `T` is a concrete shape.
      */
-    filter?: FilterString<T>;
+    filter?: FilterString<_T, F>;
     /**
      * Sort field(s): `field`, `-field` (descending), comma-separated.
      */
-    sort?: SortString<T>;
+    sort?: SortString<_T, S>;
     /**
      * Comma-separated relation field names to expand.
      */
-    expand?: ExpandString<T>;
+    expand?: ExpandString<_T, E>;
     /**
      * Explicit field projection (overrides {@link CollectionService.select}).
      */
@@ -183,9 +283,9 @@ interface ListOptions<T = ApiRecord> {
 /**
  * Options for single-record reads (`getOne`): expand + explicit fields.
  */
-interface ReadOptions<T = ApiRecord> {
+interface ReadOptions<_T = ApiRecord, E extends string = never> {
     /** Comma-separated relation field names to expand. */
-    expand?: ExpandString<T>;
+    expand?: ExpandString<_T, E>;
     /** Explicit field projection (overrides {@link CollectionService.select}). */
     fields?: string;
 }
@@ -534,8 +634,14 @@ interface RealtimeSubscribeOptions {
  * Get an instance via {@link LazypockClient.collection}.
  *
  * @typeParam T — The record shape for this collection. Defaults to {@link ApiRecord}.
+ * @typeParam TData — Write-only create/update payload shape (defaults to `never`,
+ * which falls back to `T`-derived create data).
+ * @typeParam TFields — The key set accepted by `filter`/`sort`/`expand`/`select`.
+ * Defaults to `T`. The codegen client binds a *QueryFields type that includes
+ * hidden fields — excluded from the read model but still expandable/filterable
+ * at runtime — so `expand: "hiddenRelation"` typechecks.
  */
-declare class CollectionService<T = ApiRecord, TData = never> {
+declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
     private http;
     private collectionName;
     private authStore?;
@@ -574,7 +680,7 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * `fields` param — the server returns every non-password field.
      * Pass `select("*")` to restore the default after a projection.
      */
-    select<K extends FieldKey<T> | "*">(...fields: K[]): CollectionService<T, TData>;
+    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields>;
     /**
      * Fields to send with reads:
      * 1. explicit `options.fields` (caller wins)
@@ -607,27 +713,35 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * @param perPage Records per page (default 30).
      * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
      */
-    getList<T2 = T>(page?: number, perPage?: number, options?: ListOptions<T> & RequestOptions): Promise<ListResult<T2> | null>;
+    getList<T2 = T, E extends string = never, S extends string = never, F extends string = never>(page?: number, perPage?: number, options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<ListResult<T2 & {
+        expand?: ExpandObj<E>;
+    }> | null>;
     /**
      * Fetch all records at once (auto-paginates). Mirrors PocketBase's
      * `pb.collection(name).getFullList()`.
      *
      * @param options Query params (`sort`, `filter`, `batch`, etc.) + request options.
      */
-    getFullList<T2 = T>(options?: ListOptions<T> & RequestOptions): Promise<Array<T2>>;
+    getFullList<T2 = T, E extends string = never, S extends string = never, F extends string = never>(options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<Array<T2 & {
+        expand?: ExpandObj<E>;
+    }>>;
     /**
      * Fetch the first record matching a filter (PocketBase `getFirstListItem`).
      *
      * @param filter Filter expression (e.g. `title = 'x'`).
      * @param options Optional request options.
      */
-    getFirstListItem<T2 = T>(filter: FilterString<T>, options?: ListOptions<T> & RequestOptions): Promise<T2 | null>;
+    getFirstListItem<T2 = T, F extends string = never, E extends string = never, S extends string = never>(filter: FilterString<TFields, F>, options?: ListOptions<TFields, E, S, F> & RequestOptions): Promise<(T2 & {
+        expand?: ExpandObj<E>;
+    }) | null>;
     /**
      * Get a single record by ID.
      * @param id Record ID.
      * @param options Optional request options.
      */
-    getOne(id: string, options?: ReadOptions<T> & RequestOptions): Promise<T | null>;
+    getOne<E extends string = never>(id: string, options?: ReadOptions<TFields, E> & RequestOptions): Promise<(T & {
+        expand?: ExpandObj<E>;
+    }) | null>;
     /**
      * Create a new record.
      * @param data Record fields. When `T` is a concrete shape (e.g. a generated
@@ -680,7 +794,7 @@ declare class CollectionService<T = ApiRecord, TData = never> {
      * `types.schemas`). Enables schema-aware defaults: hidden fields are
      * excluded from responses, select/expand are validated.
      */
-    withSchema(schema: CollectionSchema): CollectionService<T, TData>;
+    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields>;
     /**
      * Subscribe to realtime changes for this collection.
      * The event's `action` is one of `"create" | "update" | "delete"` and the