@functional-systems/lambdadb 0.3.0-dev.4 → 0.3.1

package/src/client.ts

@@ -30,14 +30,19 @@ import { unwrapAsync, OK, ERR } from "./types/fp.js";
 import type { Result } from "./types/fp.js";
 import type * as operations from "./models/operations/index.js";
 import type * as models from "./models/index.js";
-import type {
-  CreateCollectionInput,
-  UpdateCollectionInput,
-  QueryCollectionInput,
-  QueryCollectionResponse,
-  QueryCollectionDoc,
-  ListDocsInput,
-  ListDocsResponse,
+import {
+  listCollectionsResponseWithDates,
+  getCollectionResponseWithDates,
+  type CreateCollectionInput,
+  type UpdateCollectionInput,
+  type QueryCollectionInput,
+  type QueryCollectionResponse,
+  type QueryCollectionDoc,
+  type ListDocsInput,
+  type ListDocsResponse,
+  type ListCollectionsInput,
+  type ListCollectionsResponseWithDates,
+  type GetCollectionResponseWithDates,
   UpsertDocsInput,
   UpdateDocsInput,
   DeleteDocsInput,
@@ -46,9 +51,7 @@ import type {
   FetchDocsDoc,
   BulkUpsertInput,
   MessageResponse,
-  ListCollectionsResponse,
   CreateCollectionResponse,
-  GetCollectionResponse,
   UpdateCollectionResponse,
   GetBulkUpsertDocsResponse,
 } from "./types/public.js";
@@ -155,19 +158,66 @@ export class LambdaDBClient extends LambdaDBCore {
   }
 
   /**
-   * List all collections in the project.
+   * List collections in the project (with optional pagination). Timestamp fields are returned as Date.
    */
-  async listCollections(options?: RequestOptions) {
-    return unwrapAsync(collectionsList(this, options));
+  async listCollections(
+    params?: ListCollectionsInput,
+    options?: RequestOptions,
+  ): Promise<ListCollectionsResponseWithDates> {
+    const res = await unwrapAsync(collectionsList(this, params, options));
+    return listCollectionsResponseWithDates(res);
   }
 
   /**
-   * List all collections (Safe: returns Result instead of throwing).
+   * List collections (Safe: returns Result instead of throwing). Timestamp fields are Date.
    */
   async listCollectionsSafe(
+    params?: ListCollectionsInput,
     options?: RequestOptions,
-  ): Promise<Result<ListCollectionsResponse, ListCollectionsError>> {
-    return await collectionsList(this, options);
+  ): Promise<Result<ListCollectionsResponseWithDates, ListCollectionsError>> {
+    const result = await collectionsList(this, params, options);
+    if (!result.ok) return result;
+    return OK(listCollectionsResponseWithDates(result.value));
+  }
+
+  /**
+   * Iterate over all pages of collections. Yields one page per API response.
+   * Use this to process many collections without loading everything into memory.
+   *
+   * @example
+   * for await (const page of client.listCollectionsPages({ size: 20 })) {
+   *   console.log(page.collections.length, page.nextPageToken ?? "last page");
+   * }
+   */
+  async *listCollectionsPages(
+    params?: ListCollectionsInput,
+    options?: RequestOptions,
+  ): AsyncGenerator<ListCollectionsResponseWithDates> {
+    let pageToken: string | undefined = params?.pageToken;
+    const baseParams: ListCollectionsInput = { size: params?.size, pageToken };
+    while (true) {
+      const page = await this.listCollections(
+        { ...baseParams, pageToken } as ListCollectionsInput,
+        options,
+      );
+      yield page;
+      pageToken = page.nextPageToken;
+      if (pageToken == null || pageToken === "") break;
+    }
+  }
+
+  /**
+   * Fetch all collections across pages and return a single list. Uses listCollectionsPages internally.
+   */
+  async listAllCollections(
+    params?: ListCollectionsInput,
+    options?: RequestOptions,
+  ): Promise<{ collections: ListCollectionsResponseWithDates["collections"] }> {
+    const collections: ListCollectionsResponseWithDates["collections"] = [];
+    for await (const page of this.listCollectionsPages(params, options)) {
+      collections.push(...page.collections);
+    }
+    return { collections };
   }
 
   /**
@@ -201,21 +251,28 @@ export class CollectionHandle {
   ) {}
 
   /**
-   * Get metadata of this collection.
+   * Get metadata of this collection. Timestamp fields are returned as Date.
    */
-  async get(options?: RequestOptions) {
-    return unwrapAsync(
+  async get(options?: RequestOptions): Promise<GetCollectionResponseWithDates> {
+    const res = await unwrapAsync(
       collectionsGet(this.client, { collectionName: this.collectionName }, options),
     );
+    return getCollectionResponseWithDates(res);
   }
 
   /**
-   * Get metadata of this collection (Safe: returns Result instead of throwing).
+   * Get metadata of this collection (Safe: returns Result instead of throwing). Timestamp fields are Date.
    */
   async getSafe(
     options?: RequestOptions,
-  ): Promise<Result<GetCollectionResponse, GetCollectionError>> {
-    return await collectionsGet(this.client, { collectionName: this.collectionName }, options);
+  ): Promise<Result<GetCollectionResponseWithDates, GetCollectionError>> {
+    const result = await collectionsGet(
+      this.client,
+      { collectionName: this.collectionName },
+      options,
+    );
+    if (!result.ok) return result;
+    return OK(getCollectionResponseWithDates(result.value));
   }
 
   /**

package/src/funcs/collectionsList.ts

@@ -3,6 +3,7 @@
  */
 
 import { LambdaDBCore } from "../core.js";
+import { encodeFormQuery } from "../lib/encodings.js";
 import * as M from "../lib/matchers.js";
 import { compactMap } from "../lib/primitives.js";
 import { RequestOptions } from "../lib/sdks.js";
@@ -28,6 +29,7 @@ import { Result } from "../types/fp.js";
  */
 export function collectionsList(
   client: LambdaDBCore,
+  request?: operations.ListCollectionsRequest,
   options?: RequestOptions,
 ): APIPromise<
   Result<
@@ -48,12 +50,14 @@ export function collectionsList(
 > {
   return new APIPromise($do(
     client,
+    request,
     options,
   ));
 }
 
 async function $do(
   client: LambdaDBCore,
+  request?: operations.ListCollectionsRequest,
   options?: RequestOptions,
 ): Promise<
   [
@@ -77,6 +81,11 @@ async function $do(
 > {
   const path = pathToFunc("/collections")();
 
+  const query = encodeFormQuery({
+    "pageToken": request?.pageToken,
+    "size": request?.size,
+  });
+
   const headers = new Headers(compactMap({
     Accept: "application/json",
   }));
@@ -116,6 +125,7 @@ async function $do(
     baseURL: options?.serverURL,
     path: path,
     headers: headers,
+    query: query,
     userAgent: client._options.userAgent,
     timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
   }, options);

package/src/models/collectionresponse.ts

@@ -51,6 +51,18 @@ export type CollectionResponse = {
    * Status
    */
   collectionStatus: Status;
+  /**
+   * Collection creation time in seconds since the Unix epoch.
+   */
+  createdAt: number;
+  /**
+   * Collection last update time in seconds since the Unix epoch.
+   */
+  updatedAt: number;
+  /**
+   * Collection data last update time in seconds since the Unix epoch.
+   */
+  dataUpdatedAt: number;
 };
 
 /** @internal */
@@ -69,6 +81,9 @@ export const CollectionResponse$inboundSchema: z.ZodType<
   sourceCollectionName: z.string().optional(),
   sourceCollectionVersionId: z.string().optional(),
   collectionStatus: Status$inboundSchema,
+  createdAt: z.number().int(),
+  updatedAt: z.number().int(),
+  dataUpdatedAt: z.number().int(),
 });
 
 export function collectionResponseFromJSON(

package/src/models/operations/listcollections.ts

@@ -8,11 +8,39 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
 
+/**
+ * Request parameters for listing collections (pagination).
+ */
+export type ListCollectionsRequest = {
+  /**
+   * Max number of collections to return at once.
+   */
+  size?: number | undefined;
+  /**
+   * Next page token.
+   */
+  pageToken?: string | undefined;
+};
+
+/** @internal */
+export const ListCollectionsRequest$outboundSchema: z.ZodType<
+  ListCollectionsRequest,
+  z.ZodTypeDef,
+  ListCollectionsRequest
+> = z.object({
+  size: z.number().int().min(1).max(100).optional(),
+  pageToken: z.string().optional(),
+});
+
 /**
  * A list of collections matched with a projectName.
  */
 export type ListCollectionsResponse = {
   collections: Array<models.CollectionResponse>;
+  /**
+   * Next page token.
+   */
+  nextPageToken?: string | undefined;
 };
 
 /** @internal */
@@ -22,6 +50,7 @@ export const ListCollectionsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   collections: z.array(models.CollectionResponse$inboundSchema),
+  nextPageToken: z.string().optional(),
 });
 
 export function listCollectionsResponseFromJSON(

package/src/sdk/collections.ts

@@ -27,10 +27,12 @@ export class Collections extends ClientSDK {
    * List all collections in an existing project.
    */
   async list(
+    request?: operations.ListCollectionsRequest,
     options?: RequestOptions,
   ): Promise<operations.ListCollectionsResponse> {
     return unwrapAsync(collectionsList(
       this,
+      request,
       options,
     ));
   }

package/src/types/public.ts

@@ -14,10 +14,17 @@ export type { FetchDocsRequestBody as FetchDocsInput } from "../models/operation
 export type { BulkUpsertDocsRequestBody as BulkUpsertInput } from "../models/operations/bulkupsertdocs.js";
 
 import type { ListDocsRequest } from "../models/operations/listdocs.js";
+import type { ListCollectionsRequest } from "../models/operations/listcollections.js";
 
 /** Parameters for listing documents (size, pageToken). */
 export type ListDocsInput = Pick<ListDocsRequest, "size" | "pageToken">;
 
+/** Parameters for listing collections (size, pageToken). */
+export type ListCollectionsInput = Pick<
+  ListCollectionsRequest,
+  "size" | "pageToken"
+>;
+
 // ---- Response types ----
 export type { ListCollectionsResponse } from "../models/operations/listcollections.js";
 export type { CreateCollectionResponse } from "../models/operations/createcollection.js";
@@ -43,3 +50,66 @@ export type {
   FieldsSelectorUnion,
   CollectionResponse,
 } from "../models/index.js";
+
+// ---- Timestamp helpers (Unix seconds → Date) ----
+import type { CollectionResponse as CollectionResponseModel } from "../models/index.js";
+
+/**
+ * Collection response with timestamp fields as Date (for better DX).
+ * Use {@link collectionResponseWithDates} to convert API response.
+ */
+export type CollectionResponseWithDates = Omit<
+  CollectionResponseModel,
+  "createdAt" | "updatedAt" | "dataUpdatedAt"
+> & {
+  createdAt?: Date | undefined;
+  updatedAt?: Date | undefined;
+  dataUpdatedAt?: Date | undefined;
+};
+
+/**
+ * List collections response with timestamp fields as Date.
+ */
+export type ListCollectionsResponseWithDates = {
+  collections: CollectionResponseWithDates[];
+  nextPageToken?: string | undefined;
+};
+
+/**
+ * Converts Unix-second timestamp fields to Date. Safe to call on partial responses.
+ */
+export function collectionResponseWithDates(
+  c: CollectionResponseModel,
+): CollectionResponseWithDates {
+  const { createdAt, updatedAt, dataUpdatedAt, ...rest } = c;
+  const out: CollectionResponseWithDates = { ...rest };
+  if (createdAt != null) out.createdAt = new Date(createdAt * 1000);
+  if (updatedAt != null) out.updatedAt = new Date(updatedAt * 1000);
+  if (dataUpdatedAt != null)
+    out.dataUpdatedAt = new Date(dataUpdatedAt * 1000);
+  return out;
+}
+
+/** Converts ListCollectionsResponse to use Date for timestamp fields. */
+export function listCollectionsResponseWithDates(res: {
+  collections: CollectionResponseModel[];
+  nextPageToken?: string | undefined;
+}): ListCollectionsResponseWithDates {
+  const out: ListCollectionsResponseWithDates = {
+    collections: res.collections.map(collectionResponseWithDates),
+  };
+  if (res.nextPageToken !== undefined) out.nextPageToken = res.nextPageToken;
+  return out;
+}
+
+/** Get collection response with timestamp fields as Date. */
+export type GetCollectionResponseWithDates = {
+  collection: CollectionResponseWithDates;
+};
+
+/** Converts GetCollectionResponse to use Date for timestamp fields. */
+export function getCollectionResponseWithDates(res: {
+  collection: CollectionResponseModel;
+}): GetCollectionResponseWithDates {
+  return { collection: collectionResponseWithDates(res.collection) };
+}