lazypock 0.1.0 → 0.1.2

package/src/codegen.ts

@@ -0,0 +1,149 @@
+// ── Codegen ─────────────────────────────────────────────
+// Generates a `lazypock.types.ts` module from the live API schema.
+//
+// The generated file exports:
+//   - One interface per collection (e.g. `PostsRecord`)
+//   - A `LazypockCollections` map: { posts: PostsRecord; users: UsersRecord; ... }
+//   - A `createClient()` factory pre-bound to those types, so
+//     `client.collection("posts").create({ title: "x" })` is fully type-checked.
+//
+// The CLI in `src/cli.ts` wires this to `GET /collections`.
+
+import type { CollectionSchema, SchemaField } from "./schema";
+import { fieldTypeScriptType } from "./typegen";
+
+/** Format a raw collection name into a valid TS identifier (PascalCase). */
+export function collectionTypeName(name: string): string {
+	return name
+		.split(/[^a-zA-Z0-9]+/)
+		.filter(Boolean)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join("")
+		.replace(/^[0-9]/, "_$&");
+}
+
+/** Interface member name — sanitize hyphens/spaces but keep readability. */
+export function fieldKey(name: string): string {
+	return name.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+
+
+/**
+ * Generate the full TypeScript source for the typed SDK module.
+ *
+ * @param collections Collections fetched from the API.
+ * @param options Generation options.
+ */
+export 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 {
+	const {
+		packageName = "lazypock",
+		includeBaseFields = true,
+		skipSystem = false,
+	} = options;
+
+	const filtered = skipSystem
+		? collections.filter(
+				(c) => !c.system && !c.name.startsWith("_") && c.name !== "users",
+			)
+		: collections;
+
+	const sections: string[] = [];
+	sections.push(`// ── Auto-generated by lazypock-ts ──────────────────────────
+// Do not edit by hand. Regenerate with: npx lazypock-gen
+// Schema snapshot: ${new Date().toISOString()}`);
+
+	if (includeBaseFields) {
+		sections.push(`export interface BaseRecord {
+  id: string;
+  collectionId: string;
+  collectionName: string;
+  created: string;
+  updated: string;
+}`);
+	}
+
+	// One interface per collection
+	for (const coll of filtered) {
+		const typeName = collectionTypeName(coll.name);
+		const fields = coll.fields ?? [];
+		const lines = fields.map((f) => memberLine(f)).filter((l) => l !== "");
+		const body = lines.join("\n");
+		sections.push(
+			`export interface ${typeName}Record${renderInterface({
+				extends: includeBaseFields ? "BaseRecord" : undefined,
+				body,
+			})}`,
+		);
+	}
+
+	// Auth collection type
+	sections.push(`export interface AuthRecord extends BaseRecord {
+  email: string;
+  verified: boolean;
+}`);
+
+	// Collections map
+	const mapEntries = filtered
+		.map(
+			(c) =>
+				`  "${c.name}": ${collectionTypeName(c.name)}Record${
+					c.type === "auth" ? " & AuthRecord" : ""
+				};`,
+		)
+		.join("\n");
+	sections.push(`export interface LazypockCollections {
+${mapEntries}
+}`);
+
+	// createClient factory
+	sections.push(`import { LazypockClient, type LazypockClientOptions, type CollectionService } from "${packageName}";
+
+/**
+ * Create a Lazypock client typed against this schema snapshot.
+ * Collection access is fully type-checked:
+ *   client.collection("posts").create({ title: "x" }) // title must exist
+ */
+export function createClient(options: LazypockClientOptions): TypedClient {
+  return new TypedClient(options);
+}
+
+export class TypedClient extends LazypockClient {
+  override collection<K extends keyof LazypockCollections>(name: K): CollectionService<LazypockCollections[K]>;
+  override collection(name: string): CollectionService<unknown> {
+    return super.collection(name) as unknown as CollectionService<unknown>;
+  }
+}`);
+
+	return sections.join("\n\n") + "\n";
+}
+
+/**
+ * Render the interface body including the extends clause.
+ * Empty body → ` extends BaseRecord {}` (valid TS).
+ */
+function renderInterface(opts: { extends?: string; body: string }): string {
+	const ext = opts.extends ? ` extends ${opts.extends}` : "";
+	if (!opts.body) return `${ext} {}`;
+	return `${ext} {\n${opts.body}\n}`;
+}
+
+/** Render a single interface member line for a field. */
+function memberLine(f: SchemaField): string {
+	const key = fieldKey(f.name);
+	const req = f.required || f.type === "password" ? "" : "?";
+	const type = fieldTypeScriptType(f);
+	// `never` members (passwords) are omitted from read models.
+	if (type === "never") return "";
+	return `  ${JSON.stringify(key)}${req}: ${type};`;
+}

package/src/collection.ts

@@ -3,22 +3,75 @@
 
 import type { HttpClient } from "./http";
 import type { AuthStore, AuthModel } from "./auth";
-import type { ApiRecord, ListResult, RequestOptions } from "./types";
+import type {
+	ApiRecord,
+	ListResult,
+	RequestOptions,
+	CreateData,
+	UpdateData,
+} from "./types";
+import type { RealtimeService } from "./realtime";
+
+/**
+ * A realtime record-change event delivered to subscription callbacks.
+ * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
+ */
+export interface RealtimeMessage {
+	action: "create" | "update" | "delete";
+	record: Record<string, unknown>;
+	topic?: string;
+}
+
+/** Subscription callback for a collection's realtime events. */
+export type RealtimeCallback = (e: RealtimeMessage) => void;
+
+/** Raw event passed by the low-level realtime service. */
+interface RealtimeEventLike {
+	event: string;
+	topic: string;
+	payload?: Record<string, unknown>;
+}
+
+/** Map a raw event/action to a normalised create/update/delete action. */
+function normalizeAction(
+	event: string,
+	rawAction?: unknown,
+): RealtimeMessage["action"] {
+	if (typeof rawAction === "string") {
+		const a = rawAction.toLowerCase();
+		if (a === "create" || a === "update" || a === "delete") {
+			return a;
+		}
+	}
+	if (event === "record_change") return "update";
+	if (event === "create" || event === "record_create") return "create";
+	if (event === "delete" || event === "record_delete") return "delete";
+	return "update";
+}
 
 /**
  * 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}.
  */
-export class CollectionService {
+export class CollectionService<T = ApiRecord> {
 	private http: HttpClient;
 	private collectionName: string;
 	private authStore?: AuthStore;
+	private realtime?: RealtimeService;
 
 	/** @internal */
-	constructor(http: HttpClient, collectionName: string, authStore?: AuthStore) {
+	constructor(
+		http: HttpClient,
+		collectionName: string,
+		authStore?: AuthStore,
+		realtime?: RealtimeService,
+	) {
 		this.http = http;
 		this.collectionName = collectionName;
 		this.authStore = authStore;
+		this.realtime = realtime;
 	}
 
 	private encodeId(id: string): string {
@@ -30,7 +83,7 @@ export class CollectionService {
 	 * @param params Query parameters including `filter`, `sort`, `page`, `perPage`, `expand`.
 	 * @param options Optional request options.
 	 */
-	list<T = ApiRecord>(
+	list(
 		params?: Record<string, string>,
 		options?: RequestOptions,
 	): Promise<ListResult<T> | null> {
@@ -46,10 +99,7 @@ export class CollectionService {
 	 * @param id Record ID.
 	 * @param options Optional request options.
 	 */
-	getOne<T = ApiRecord>(
-		id: string,
-		options?: RequestOptions,
-	): Promise<T | null> {
+	getOne(id: string, options?: RequestOptions): Promise<T | null> {
 		return this.http.get<T>(
 			"/" + this.encodeId(this.collectionName) + "/" + this.encodeId(id),
 			options,
@@ -58,11 +108,12 @@ export class CollectionService {
 
 	/**
 	 * Create a new record.
-	 * @param data Record fields.
+	 * @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<T = ApiRecord>(
-		data: Record<string, unknown>,
+	create(
+		data: T extends ApiRecord ? Record<string, unknown> : CreateData<T>,
 		options?: RequestOptions,
 	): Promise<T | null> {
 		return this.http.post<T>(
@@ -75,12 +126,13 @@ export class CollectionService {
 	/**
 	 * Update a record by ID.
 	 * @param id Record ID.
-	 * @param data Updated record fields.
+	 * @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<T = ApiRecord>(
+	update(
 		id: string,
-		data: Record<string, unknown>,
+		data: T extends ApiRecord ? Record<string, unknown> : UpdateData<T>,
 		options?: RequestOptions,
 	): Promise<T | null> {
 		return this.http.patch<T>(
@@ -111,11 +163,12 @@ export class CollectionService {
 		options?: RequestOptions,
 	): Promise<{ field: string; targetCollection: string }[] | null> {
 		const data = await this.http.get<{
-			fields?: { name: string; type: string; options?: Record<string, string> }[];
-		}>(
-			"/collections/" + this.encodeId(this.collectionName),
-			options,
-		);
+			fields?: {
+				name: string;
+				type: string;
+				options?: Record<string, string>;
+			}[];
+		}>("/collections/" + this.encodeId(this.collectionName), options);
 		if (!data?.fields) return null;
 		return data.fields
 			.filter((f) => f.type === "relation" && f.options?.collection)
@@ -125,6 +178,71 @@ export class CollectionService {
 			}));
 	}
 
+	/**
+	 * 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> {
+		return this as unknown as CollectionService<TRecord>;
+	}
+
+	// ── Realtime Subscriptions (PocketBase-style) ──
+
+	/**
+	 * 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 {
+		if (!this.realtime) {
+			console.warn("[lazypock] No realtime service configured.");
+			return () => {};
+		}
+		const topic =
+			"collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+		const handler = (raw: RealtimeEventLike) => {
+			const record = (raw.payload?.["record"] ?? {}) as Record<string, unknown>;
+			callback({
+				action: normalizeAction(raw.event, raw.payload?.["action"]),
+				record,
+				topic: raw.topic,
+			});
+		};
+		this.realtime.ensureConnected();
+		this.realtime.subscribe(topic, handler as never);
+		return () => this.realtime?.unsubscribe(topic, handler as never);
+	}
+
+	/**
+	 * Unsubscribe all callbacks from this collection (or a specific record).
+	 * @param recordId Optional record id; omitting it unsubs everything.
+	 */
+	unsubscribe(recordId?: string): void {
+		const topic =
+			"collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+		this.realtime?.unsubscribe(topic);
+	}
+
 	// ── Auth Collection Methods ──
 
 	/**
@@ -135,7 +253,9 @@ export class CollectionService {
 		identity: string,
 		password: string,
 		options?: RequestOptions,
-	): Promise<({ token: string; record: ApiRecord } & Record<string, unknown>) | null> {
+	): Promise<
+		({ token: string; record: ApiRecord } & Record<string, unknown>) | null
+	> {
 		const data = await this.http.post<
 			{ token: string; record: ApiRecord } & Record<string, unknown>
 		>(
@@ -156,7 +276,9 @@ export class CollectionService {
 	 */
 	async authRefresh(
 		options?: RequestOptions,
-	): Promise<({ token: string; record: ApiRecord } & Record<string, unknown>) | null> {
+	): Promise<
+		({ token: string; record: ApiRecord } & Record<string, unknown>) | null
+	> {
 		const data = await this.http.post<
 			{ token: string; record: ApiRecord } & Record<string, unknown>
 		>(
@@ -174,6 +296,8 @@ export class CollectionService {
 	/**
 	 * Get available auth methods for this collection.
 	 */
+	// ── end Realtime ──
+
 	async authMethods(
 		options?: RequestOptions,
 	): Promise<Record<string, unknown> | null> {