lazypock 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -1,12 +1,36 @@
-/** Shape of a record returned from any collection. */
-interface ApiRecord {
+/**
+ * Base shape every record returned from any collection satisfies.
+ * Generated record interfaces extend this.
+ */
+interface BaseRecordFields {
     id: string;
     collectionId: string;
     collectionName: string;
     created: string;
     updated: string;
+}
+/** Shape of a record returned from any collection. */
+interface ApiRecord extends BaseRecordFields {
     [key: string]: unknown;
 }
+/**
+ * Structural marker for concrete record shapes (generated or hand-written).
+ * Used to differentiate a typed collection service from the untyped default.
+ */
+type RecordShape = Record<string, unknown>;
+/** System fields every record carries — not user-provided on create. */
+type SystemFields = "id" | "collectionId" | "collectionName" | "created" | "updated";
+/**
+ * Data accepted by `create()`: any subset of `T`'s fields, but
+ * never the system fields. Unknown/extra keys are rejected at compile
+ * time via excess-property checking (object literals).
+ */
+type CreateData<T> = Partial<Omit<T, SystemFields>>;
+/**
+ * Data accepted by `update()`: any subset of `T`'s fields.
+ * Unknown/extra keys are rejected at compile time.
+ */
+type UpdateData<T> = Partial<Omit<T, SystemFields>>;
 /** Paginated list response matching PocketBase format. */
 interface ListResult<T = ApiRecord> {
     items: T[];
@@ -159,78 +183,6 @@ declare class HttpClient {
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T | null>;
 }
 
-/**
- * Typed CRUD service for a single dynamic collection.
- * Get an instance via {@link LazypockClient.collection}.
- */
-declare class CollectionService {
-    private http;
-    private collectionName;
-    private authStore?;
-    /** @internal */
-    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore);
-    private encodeId;
-    /**
-     * List records with optional filter/sort/pagination.
-     * @param params Query parameters including `filter`, `sort`, `page`, `perPage`, `expand`.
-     * @param options Optional request options.
-     */
-    list<T = ApiRecord>(params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<T> | null>;
-    /**
-     * Get a single record by ID.
-     * @param id Record ID.
-     * @param options Optional request options.
-     */
-    getOne<T = ApiRecord>(id: string, options?: RequestOptions): Promise<T | null>;
-    /**
-     * Create a new record.
-     * @param data Record fields.
-     * @param options Optional request options.
-     */
-    create<T = ApiRecord>(data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
-    /**
-     * Update a record by ID.
-     * @param id Record ID.
-     * @param data Updated record fields.
-     * @param options Optional request options.
-     */
-    update<T = ApiRecord>(id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
-    /**
-     * Delete a record by ID.
-     * @param id Record ID.
-     * @param options Optional request options.
-     */
-    delete(id: string, options?: RequestOptions): Promise<null>;
-    /**
-     * Get a list of expandable (relation) fields for this collection.
-     * Useful for constructing `expand` query parameters.
-     */
-    expandFields(options?: RequestOptions): Promise<{
-        field: string;
-        targetCollection: string;
-    }[] | null>;
-    /**
-     * Authenticate with email/password against this auth collection.
-     * Stores the returned token and user model in the auth store.
-     */
-    authWithPassword(identity: string, password: string, options?: RequestOptions): Promise<({
-        token: string;
-        record: ApiRecord;
-    } & Record<string, unknown>) | null>;
-    /**
-     * Refresh the auth token for the currently authenticated user.
-     * Updates the stored token and user model.
-     */
-    authRefresh(options?: RequestOptions): Promise<({
-        token: string;
-        record: ApiRecord;
-    } & Record<string, unknown>) | null>;
-    /**
-     * Get available auth methods for this collection.
-     */
-    authMethods(options?: RequestOptions): Promise<Record<string, unknown> | null>;
-}
-
 interface RealtimeEvent {
     event: string;
     topic: string;
@@ -272,6 +224,21 @@ declare class RealtimeService {
     onError?: (err: Event) => void;
     private url;
     private token;
+    /** Whether the WebSocket is currently open. */
+    get isOpen(): boolean;
+    /**
+     * The most recently used WebSocket URL (set on {@link connect}).
+     * Useful for SDK convenience methods that auto-connect before subscribing.
+     */
+    get lastUrl(): string;
+    /** The auth token configured for this connection (set on connect). */
+    get lastToken(): string | undefined;
+    /**
+     * Set the socket URL. Useful before subscribing so the SDK can
+     * auto-connect on the first {@link subscribe}.
+     */
+    setUrl(url: string): void;
+    ensureConnected(): void;
     connect(opts: RealtimeConnectOpts): void;
     disconnect(): void;
     /**
@@ -295,6 +262,130 @@ declare class RealtimeService {
     private clearReconnectTimer;
 }
 
+/**
+ * A realtime record-change event delivered to subscription callbacks.
+ * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
+ */
+interface RealtimeMessage {
+    action: "create" | "update" | "delete";
+    record: Record<string, unknown>;
+    topic?: string;
+}
+/** Subscription callback for a collection's realtime events. */
+type RealtimeCallback = (e: RealtimeMessage) => void;
+/**
+ * Typed CRUD service for a single dynamic collection.
+ * Get an instance via {@link LazypockClient.collection}.
+ *
+ * @typeParam T — The record shape for this collection. Defaults to {@link ApiRecord}.
+ */
+declare class CollectionService<T = ApiRecord> {
+    private http;
+    private collectionName;
+    private authStore?;
+    private realtime?;
+    /** @internal */
+    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService);
+    private encodeId;
+    /**
+     * List records with optional filter/sort/pagination.
+     * @param params Query parameters including `filter`, `sort`, `page`, `perPage`, `expand`.
+     * @param options Optional request options.
+     */
+    list(params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<T> | null>;
+    /**
+     * Get a single record by ID.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    getOne(id: string, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Create a new record.
+     * @param data Record fields. When `T` is a concrete shape (e.g. a generated
+     * record type), excess/unknown fields are rejected at compile time.
+     * @param options Optional request options.
+     */
+    create(data: T extends ApiRecord ? Record<string, unknown> : CreateData<T>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Update a record by ID.
+     * @param id Record ID.
+     * @param data Updated record fields. When `T` is a concrete shape, `data`
+     * must be a partial of `T` — unknown fields are rejected.
+     * @param options Optional request options.
+     */
+    update(id: string, data: T extends ApiRecord ? Record<string, unknown> : UpdateData<T>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Delete a record by ID.
+     * @param id Record ID.
+     * @param options Optional request options.
+     */
+    delete(id: string, options?: RequestOptions): Promise<null>;
+    /**
+     * Get a list of expandable (relation) fields for this collection.
+     * Useful for constructing `expand` query parameters.
+     */
+    expandFields(options?: RequestOptions): Promise<{
+        field: string;
+        targetCollection: string;
+    }[] | null>;
+    /**
+     * Cast this service to a specific record shape.
+     * Use when you have a hand-written or generated interface for the
+     * collection and want compile-time checking of create/update/list.
+     *
+     * @example
+     * ```ts
+     * interface Post {
+     *   id: string;
+     *   title: string;
+     *   published: boolean;
+     * }
+     * const posts = client.collection("posts").typed<Post>();
+     * await posts.create({ title: "Hi", published: true }); // ✓
+     * await posts.create({ nope: 1 }); // ✗ compile error
+     * ```
+     */
+    typed<TRecord = ApiRecord>(): CollectionService<TRecord>;
+    /**
+     * Subscribe to realtime changes for this collection.
+     * The event's `action` is one of `"create" | "update" | "delete"`.
+     *
+     * Access is governed by the collection's `listRule` (PocketBase semantics):
+     * public collections allow anonymous subscriptions; other collections
+     * require a matching logged-in user or superuser.
+     *
+     * @param callback Received on every record change.
+     * @param recordId Optional — subscribe to a single record instead of `*`.
+     * @returns A function that unsubscribes this callback.
+     */
+    subscribe(callback: RealtimeCallback, recordId?: string): () => void;
+    /**
+     * Unsubscribe all callbacks from this collection (or a specific record).
+     * @param recordId Optional record id; omitting it unsubs everything.
+     */
+    unsubscribe(recordId?: string): void;
+    /**
+     * Authenticate with email/password against this auth collection.
+     * Stores the returned token and user model in the auth store.
+     */
+    authWithPassword(identity: string, password: string, options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Refresh the auth token for the currently authenticated user.
+     * Updates the stored token and user model.
+     */
+    authRefresh(options?: RequestOptions): Promise<({
+        token: string;
+        record: ApiRecord;
+    } & Record<string, unknown>) | null>;
+    /**
+     * Get available auth methods for this collection.
+     */
+    authMethods(options?: RequestOptions): Promise<Record<string, unknown> | null>;
+}
+
 /** Response shape from the server file endpoints */
 interface FileRecord {
     id: string;
@@ -341,6 +432,76 @@ declare class FilesService {
     delete(fileId: string, options?: RequestOptions): Promise<null>;
 }
 
+/** A single field definition as returned by `GET /collections`. */
+interface SchemaField {
+    id?: string;
+    name: string;
+    type: string;
+    required?: boolean;
+    unique?: boolean;
+    options?: {
+        /** For relation fields: the target collection name. */
+        collection?: string;
+        /** Max selectable/related items (multi when > 1). */
+        maxSelect?: number;
+        /** Allowed values for select / multi_select fields. */
+        values?: string[];
+    } & Record<string, unknown>;
+    indexed?: boolean;
+    hidden?: boolean;
+    system?: boolean;
+    sort_order?: number;
+}
+/** A collection definition as returned by `GET /collections`. */
+interface CollectionSchema {
+    id?: string;
+    name: string;
+    type: "base" | "auth";
+    system?: boolean;
+    fields?: SchemaField[];
+    rules?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+}
+
+/** Format a raw collection name into a valid TS identifier (PascalCase). */
+declare function collectionTypeName(name: string): string;
+/**
+ * Generate the full TypeScript source for the typed SDK module.
+ *
+ * @param collections Collections fetched from the API.
+ * @param options Generation options.
+ */
+declare function generateTypes(collections: CollectionSchema[], options?: {
+    /** Import specifier for the lazypock package (default `lazypock`). */
+    packageName?: string;
+    /** Emit base record fields (id, created, updated, …). Default true. */
+    includeBaseFields?: boolean;
+    /** Skip system collections (names starting with `_` or `users`). Default false. */
+    skipSystem?: boolean;
+}): string;
+
+/**
+ * Map a single server field to its TypeScript type string.
+ * Used by the codegen CLI to emit interface members.
+ *
+ * @param field The field definition.
+ * @param fallback Fallback type for unknown field types (default `unknown`).
+ */
+declare function fieldTypeScriptType(field: SchemaField, fallback?: string): string;
+/**
+ * Returns the runtime type kind for a field — used by {@link schemaFieldType}
+ * to build structural types at runtime.
+ */
+type FieldTypeKind = "string" | "number" | "boolean" | "string-array" | "json" | "relation" | "relation-many" | "password" | "unknown";
+/** Map a server field to its runtime type kind. */
+declare function fieldTypeKind(field: SchemaField): FieldTypeKind;
+/**
+ * Derive a TypeScript field type from a {@link SchemaField} — the runtime
+ * counterpart to the codegen mapper. Lets consumers build typed clients
+ * from a fetched schema without running the CLI.
+ */
+declare function schemaFieldType(field: SchemaField): unknown;
+
 /** Options for constructing a {@link LazypockClient}. */
 interface LazypockClientOptions {
     /** API base URL (e.g. 'http://localhost:4000/api') */
@@ -351,6 +512,17 @@ interface LazypockClientOptions {
     authStore?: AuthStore;
     /** Real-time service for Phoenix Channel WebSocket subscriptions */
     realtime?: RealtimeService;
+    /**
+     * Optional schema types for generating typed services at runtime.
+     * When provided, `collection()` returns a service whose create/update
+     * inputs are validated against the mapped field types.
+     *
+     * @experimental
+     */
+    types?: {
+        /** Collection schemas fetched from the API (e.g. via `GET /collections`). */
+        schemas?: CollectionSchema[];
+    };
 }
 /**
  * Lazypock API client.
@@ -371,19 +543,40 @@ declare class LazypockClient {
     readonly realtime: RealtimeService;
     readonly files: FilesService;
     private collectionCache;
+    private schemaByName?;
     /**
      * Create a new Lazypock client.
      * @param options Configuration options.
      */
     constructor(options: LazypockClientOptions);
     /**
-     * Get or create a typed service for the given collection.
+     * Get or create a service for the given collection.
      * Services are cached after first access.
      *
+     * For typed CRUD, either:
+     *   - cast at the call site: `client.collection("posts").typed<Post>()`
+     *   - or use the typed factory: `createClient<{ posts: Post }>()`
+     *
      * @param name The collection name.
      * @returns A {@link CollectionService} instance.
      */
-    collection(name: string): CollectionService;
+    collection(name: string): CollectionService<unknown>;
+    /**
+     * Get a typed service whose record shape is derived from the schema
+     * passed via `options.types.schemas` (if available), or fall back to
+     * the untyped service otherwise.
+     *
+     * @experimental
+     */
+    collectionFor<TRecord = ApiRecord>(name: string): CollectionService<TRecord>;
+    /**
+     * Generate TypeScript types from the schemas provided to this client
+     * (via `options.types.schemas`). Returns a string ready to write to a
+     * `lazypock.types.ts` file.
+     */
+    generateTypes(options?: {
+        packageName?: string;
+    }): string;
     /** Check whether any superuser exists (for login vs setup screen routing). */
     checkSuperuser(): Promise<{
         has_superuser: boolean;
@@ -517,4 +710,32 @@ declare class LazypockClient {
     deleteRecord(coll: string, id: string, options?: RequestOptions): Promise<null>;
 }
 
-export { ApiError, type ApiRecord, type AuthModel, AuthStore, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type ListResult, RealtimeService, type RequestOptions, type StorageAdapter, getFileUrl, wsUrlFromBaseUrl };
+/**
+ * A collections map: `{ posts: PostRecord; users: UserRecord; ... }`.
+ * Generated by the codegen CLI (`npx lazypock-gen`) or written by hand.
+ */
+type LazypockCollections = Record<string, unknown>;
+/**
+ * Client typed against a {@link LazypockCollections} map.
+ *
+ * ```ts
+ * import { createClient } from "lazypock/generated";
+ * const client = createClient({ baseUrl: "http://localhost:4000/api" });
+ * const posts = await client.collection("posts").list<PostsRecord>();
+ * ```
+ */
+declare class TypedClient<TCollections extends LazypockCollections = LazypockCollections> extends LazypockClient {
+    /**
+     * Get a typed service for a collection.
+     * When `TCollections` is provided, unknown collection names are rejected.
+     * @typeParam K — Collection name (keyof TCollections).
+     */
+    collection<K extends keyof TCollections>(name: K): CollectionService<TCollections[K]>;
+}
+/**
+ * Create a {@link TypedClient}.
+ * @typeParam TCollections — Map of collection name → record shape.
+ */
+declare function createClient<TCollections extends LazypockCollections = LazypockCollections>(options: LazypockClientOptions): TypedClient<TCollections>;
+
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };