lazypock 0.10.2 → 0.11.0

package/dist/index.d.cts

@@ -231,18 +231,29 @@ type FilterString<T, F extends string = never> = F & (F extends ValidFilter<T, F
 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>;
+/**
+ * Value type of one expanded relation: the target record from the expand
+ * map (`TExpand`, e.g. the codegen-generated `PostsExpandMap`) when the key
+ * is a known relation, `unknown` otherwise.
+ */
+type ExpandValue<K extends string, TExpand> = K extends keyof TExpand ? TExpand[K] : unknown;
 /**
  * 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.
+ * segment) and each value is typed from `TExpand` — a per-collection map of
+ * relation field → target record type (the codegen CLI emits these), so
+ * `record.expand.user` is `UsersRecord`, not `unknown`.
+ *
+ * Falls back to `Record<string, unknown>` when the expand value is dynamic
+ * or absent, or when no expand map is bound (hand-written services).
  */
-type ExpandObj<E extends string> = [
+type ExpandObj<E extends string, TExpand = Record<string, unknown>> = [
     E
 ] extends [never] ? Record<string, unknown> : [
     string
-] extends [E] ? Record<string, unknown> : Partial<Record<ExpandKeys<E>, unknown>>;
+] extends [E] ? Record<string, unknown> : Partial<{
+    [K in ExpandKeys<E>]: ExpandValue<K, TExpand>;
+}>;
 /**
  * Query options for list/read operations, typed against a record shape `T`.
  *
@@ -640,8 +651,12 @@ interface RealtimeSubscribeOptions {
  * 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.
+ * @typeParam TExpand — Map of relation field → target record type. Defaults to
+ * `Record<string, unknown>`. The codegen client binds a per-collection
+ * *ExpandMap, so `record.expand.user` is typed as the target `UsersRecord`
+ * instead of `unknown`.
  */
-declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
+declare class CollectionService<T = ApiRecord, TData = never, TFields = T, TExpand = Record<string, unknown>> {
     private http;
     private collectionName;
     private authStore?;
@@ -680,7 +695,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * `fields` param — the server returns every non-password field.
      * Pass `select("*")` to restore the default after a projection.
      */
-    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields>;
+    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields, TExpand>;
     /**
      * Fields to send with reads:
      * 1. explicit `options.fields` (caller wins)
@@ -714,7 +729,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }> | null>;
     /**
      * Fetch all records at once (auto-paginates). Mirrors PocketBase's
@@ -723,7 +738,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Query params (`sort`, `filter`, `batch`, etc.) + request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }>>;
     /**
      * Fetch the first record matching a filter (PocketBase `getFirstListItem`).
@@ -732,7 +747,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Optional request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }) | null>;
     /**
      * Get a single record by ID.
@@ -740,7 +755,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Optional request options.
      */
     getOne<E extends string = never>(id: string, options?: ReadOptions<TFields, E> & RequestOptions): Promise<(T & {
-        expand?: ExpandObj<E>;
+        expand?: ExpandObj<E, TExpand>;
     }) | null>;
     /**
      * Create a new record.
@@ -794,7 +809,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * `types.schemas`). Enables schema-aware defaults: hidden fields are
      * excluded from responses, select/expand are validated.
      */
-    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields>;
+    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields, TExpand>;
     /**
      * Subscribe to realtime changes for this collection.
      * The event's `action` is one of `"create" | "update" | "delete"` and the

package/dist/index.d.ts

@@ -231,18 +231,29 @@ type FilterString<T, F extends string = never> = F & (F extends ValidFilter<T, F
 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>;
+/**
+ * Value type of one expanded relation: the target record from the expand
+ * map (`TExpand`, e.g. the codegen-generated `PostsExpandMap`) when the key
+ * is a known relation, `unknown` otherwise.
+ */
+type ExpandValue<K extends string, TExpand> = K extends keyof TExpand ? TExpand[K] : unknown;
 /**
  * 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.
+ * segment) and each value is typed from `TExpand` — a per-collection map of
+ * relation field → target record type (the codegen CLI emits these), so
+ * `record.expand.user` is `UsersRecord`, not `unknown`.
+ *
+ * Falls back to `Record<string, unknown>` when the expand value is dynamic
+ * or absent, or when no expand map is bound (hand-written services).
  */
-type ExpandObj<E extends string> = [
+type ExpandObj<E extends string, TExpand = Record<string, unknown>> = [
     E
 ] extends [never] ? Record<string, unknown> : [
     string
-] extends [E] ? Record<string, unknown> : Partial<Record<ExpandKeys<E>, unknown>>;
+] extends [E] ? Record<string, unknown> : Partial<{
+    [K in ExpandKeys<E>]: ExpandValue<K, TExpand>;
+}>;
 /**
  * Query options for list/read operations, typed against a record shape `T`.
  *
@@ -640,8 +651,12 @@ interface RealtimeSubscribeOptions {
  * 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.
+ * @typeParam TExpand — Map of relation field → target record type. Defaults to
+ * `Record<string, unknown>`. The codegen client binds a per-collection
+ * *ExpandMap, so `record.expand.user` is typed as the target `UsersRecord`
+ * instead of `unknown`.
  */
-declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
+declare class CollectionService<T = ApiRecord, TData = never, TFields = T, TExpand = Record<string, unknown>> {
     private http;
     private collectionName;
     private authStore?;
@@ -680,7 +695,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * `fields` param — the server returns every non-password field.
      * Pass `select("*")` to restore the default after a projection.
      */
-    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields>;
+    select<K extends FieldKey<TFields> | "*">(...fields: K[]): CollectionService<T, TData, TFields, TExpand>;
     /**
      * Fields to send with reads:
      * 1. explicit `options.fields` (caller wins)
@@ -714,7 +729,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }> | null>;
     /**
      * Fetch all records at once (auto-paginates). Mirrors PocketBase's
@@ -723,7 +738,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Query params (`sort`, `filter`, `batch`, etc.) + request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }>>;
     /**
      * Fetch the first record matching a filter (PocketBase `getFirstListItem`).
@@ -732,7 +747,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Optional request options.
      */
     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>;
+        expand?: ExpandObj<E, TExpand>;
     }) | null>;
     /**
      * Get a single record by ID.
@@ -740,7 +755,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * @param options Optional request options.
      */
     getOne<E extends string = never>(id: string, options?: ReadOptions<TFields, E> & RequestOptions): Promise<(T & {
-        expand?: ExpandObj<E>;
+        expand?: ExpandObj<E, TExpand>;
     }) | null>;
     /**
      * Create a new record.
@@ -794,7 +809,7 @@ declare class CollectionService<T = ApiRecord, TData = never, TFields = T> {
      * `types.schemas`). Enables schema-aware defaults: hidden fields are
      * excluded from responses, select/expand are validated.
      */
-    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields>;
+    withSchema(schema: CollectionSchema): CollectionService<T, TData, TFields, TExpand>;
     /**
      * Subscribe to realtime changes for this collection.
      * The event's `action` is one of `"create" | "update" | "delete"` and the

package/dist/index.global.js

@@ -1553,6 +1553,9 @@ var Lazypock = (() => {
   updated: string;
 }`);
     }
+    const collById = new Map(
+      filtered.filter((c) => c.id !== void 0 && c.id !== "").map((c) => [String(c.id), c])
+    );
     for (const coll of filtered) {
       const typeName = collectionTypeName(coll.name);
       const fields = coll.fields ?? [];
@@ -1592,6 +1595,24 @@ var Lazypock = (() => {
           body: queryLines.join("\n")
         })}`
       );
+      const expandLines = [];
+      for (const f of fields) {
+        if (f.type !== "relation") continue;
+        const target = collById.get(String(f.options?.collectionId ?? "")) ?? filtered.find(
+          (c) => c.name === String(f.options?.collection ?? "")
+        );
+        if (!target) continue;
+        const targetType = `${collectionTypeName(target.name)}Record${target.type === "auth" ? " & AuthRecord" : ""}`;
+        const many = (f.options?.maxSelect ?? 1) > 1;
+        expandLines.push(
+          `  ${JSON.stringify(fieldKey(f.name))}: ${many ? `Array<${targetType}>` : targetType};`
+        );
+      }
+      sections.push(
+        `export interface ${typeName}ExpandMap${renderInterface({
+          body: expandLines.join("\n")
+        })}`
+      );
     }
     sections.push(`export interface AuthRecord extends BaseRecord {
   email: string;
@@ -1612,6 +1633,10 @@ ${createMapEntries}
     ).join("\n");
     sections.push(`export interface LazypockQueryFields {
 ${queryMapEntries}
+}`);
+    const expandMapEntries = filtered.map((c) => `  "${c.name}": ${collectionTypeName(c.name)}ExpandMap;`).join("\n");
+    sections.push(`export interface LazypockExpandMaps {
+${expandMapEntries}
 }`);
     const schemaEntries = collections.map(
       (c) => `  {
@@ -1665,25 +1690,31 @@ export class TypedClient extends LazypockClient {
   // The (string & {}) intersection keeps the union from collapsing to plain
   // string (which would silently kill the suggestions).
   //
-  // The service binds three types: the read model, the write-only *CreateData,
-  // and the *QueryFields (filter/sort/expand/select keys). QueryFields is what
-  // lets hidden relation fields \u2014 excluded from the read model but still
-  // expandable/filterable at runtime \u2014 typecheck:
+  // The service binds four types: the read model, the write-only *CreateData,
+  // the *QueryFields (filter/sort/expand/select keys), and the *ExpandMap
+  // (relation field \u2192 target record type). QueryFields is what lets hidden
+  // relation fields \u2014 excluded from the read model but still expandable/
+  // filterable at runtime \u2014 typecheck:
   //   client.collection("project_members").getFullList({ expand: "user" }) // \u2713
+  // ExpandMap is what types the expanded data on the result:
+  //   const [rec] = await client.collection("posts").getFullList({ expand: "user" });
+  //   rec.expand?.user // \u2713 UsersRecord, not unknown
   override collection<K extends keyof LazypockCollections | (string & {})>(
     name: K,
   ): K extends keyof LazypockCollections
     ? CollectionService<
         LazypockCollections[K],
         LazypockCreateData[K],
-        LazypockQueryFields[K]
+        LazypockQueryFields[K],
+        LazypockExpandMaps[K]
       >
     : CollectionService<unknown> {
     return super.collection(name) as K extends keyof LazypockCollections
       ? CollectionService<
           LazypockCollections[K],
           LazypockCreateData[K],
-          LazypockQueryFields[K]
+          LazypockQueryFields[K],
+          LazypockExpandMaps[K]
         >
       : CollectionService<unknown>;
   }