kernl 0.6.2 → 0.6.3

package/dist/api/__tests__/offset-page.test.js

@@ -1,510 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { OffsetPage, } from "../pagination/offset.js";
-describe("OffsetPage", () => {
-    describe("construction", () => {
-        it("should initialize with response data", () => {
-            const response = {
-                data: ["a", "b", "c"],
-                offset: 0,
-                limit: 10,
-                total: 100,
-            };
-            const loader = vi.fn();
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response,
-                loader,
-            });
-            expect(page.data).toEqual(["a", "b", "c"]);
-            expect(page.items).toEqual(["a", "b", "c"]);
-            expect(page.offset).toBe(0);
-            expect(page.limit).toBe(10);
-            expect(page.total).toBe(100);
-        });
-        it("should handle empty data array", () => {
-            const response = {
-                data: [],
-                offset: 0,
-                limit: 10,
-            };
-            const loader = vi.fn();
-            const page = new OffsetPage({
-                params: {},
-                response,
-                loader,
-            });
-            expect(page.data).toEqual([]);
-            expect(page.items).toEqual([]);
-            expect(page.last).toBe(true);
-        });
-        it("should handle null data gracefully", () => {
-            const response = {
-                data: null,
-                offset: 0,
-                limit: 10,
-            };
-            const loader = vi.fn();
-            const page = new OffsetPage({
-                params: {},
-                response,
-                loader,
-            });
-            expect(page.data).toEqual([]);
-            expect(page.items).toEqual([]);
-        });
-        it("should handle response without total", () => {
-            const response = {
-                data: ["a", "b"],
-                offset: 0,
-                limit: 10,
-            };
-            const page = new OffsetPage({
-                params: {},
-                response,
-                loader: vi.fn(),
-            });
-            expect(page.total).toBeUndefined();
-        });
-    });
-    describe("items getter", () => {
-        it("should return exact reference to data array", () => {
-            const data = ["a", "b", "c"];
-            const response = {
-                data,
-                offset: 0,
-                limit: 10,
-            };
-            const page = new OffsetPage({
-                params: {},
-                response,
-                loader: vi.fn(),
-            });
-            expect(page.items).toBe(page.data);
-        });
-    });
-    describe("last getter", () => {
-        it("should return true when data is empty", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return true when offset + limit >= total", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a"], offset: 90, limit: 10, total: 100 },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return true when offset + limit equals total exactly", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a", "b"], offset: 98, limit: 2, total: 100 },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(true);
-        });
-        it("should return false when offset + limit < total", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a", "b"], offset: 0, limit: 10, total: 100 },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(false);
-        });
-        it("should return false when total is undefined and data exists", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a", "b"], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(false);
-        });
-        it("should handle offset and limit of 0", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a"], offset: 0, limit: 0 },
-                loader: vi.fn(),
-            });
-            // With limit 0, next would be 0, so it can't progress
-            expect(page.last).toBe(false);
-        });
-        it("should handle undefined offset and limit", () => {
-            const page = new OffsetPage({
-                params: {},
-                response: {
-                    data: ["a"],
-                    offset: undefined,
-                    limit: undefined,
-                },
-                loader: vi.fn(),
-            });
-            expect(page.last).toBe(false);
-        });
-    });
-    describe("next()", () => {
-        it("should return null when last is true", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            const nextPage = await page.next();
-            expect(nextPage).toBe(null);
-        });
-        it("should fetch next page with incremented offset", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["d", "e", "f"],
-                offset: 10,
-                limit: 10,
-                total: 100,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a", "b", "c"], offset: 0, limit: 10, total: 100 },
-                loader,
-            });
-            const nextPage = await page.next();
-            expect(loader).toHaveBeenCalledTimes(1);
-            expect(loader).toHaveBeenCalledWith({
-                offset: 10,
-                limit: 10,
-            });
-            expect(nextPage).not.toBe(null);
-            expect(nextPage.data).toEqual(["d", "e", "f"]);
-            expect(nextPage.offset).toBe(10);
-        });
-        it("should calculate next offset correctly", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["x"],
-                offset: 25,
-                limit: 5,
-                total: 100,
-            });
-            const page = new OffsetPage({
-                params: { offset: 20, limit: 5 },
-                response: { data: ["a"], offset: 20, limit: 5, total: 100 },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                offset: 25,
-                limit: 5,
-            });
-        });
-        it("should preserve params across pagination", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["x"],
-                offset: 10,
-                limit: 10,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                offset: 10,
-                limit: 10,
-            });
-        });
-        it("should return instance of OffsetPage", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["d"],
-                offset: 10,
-                limit: 10,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            const nextPage = await page.next();
-            expect(nextPage).toBeInstanceOf(OffsetPage);
-        });
-        it("should handle undefined offset and limit", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["b"],
-                offset: 0,
-                limit: 0,
-            });
-            const page = new OffsetPage({
-                params: {},
-                response: {
-                    data: ["a"],
-                    offset: undefined,
-                    limit: undefined,
-                },
-                loader,
-            });
-            await page.next();
-            // offset ?? 0 + limit ?? 0 = 0
-            expect(loader).toHaveBeenCalledWith({
-                offset: 0,
-            });
-        });
-    });
-    describe("pages() generator", () => {
-        it("should yield only current page when last", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(1);
-            expect(pages[0]).toBe(page);
-        });
-        it("should yield multiple pages until last", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({
-                data: ["d", "e"],
-                offset: 3,
-                limit: 3,
-                total: 8,
-            })
-                .mockResolvedValueOnce({
-                data: ["f", "g"],
-                offset: 6,
-                limit: 3,
-                total: 8,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 3 },
-                response: { data: ["a", "b", "c"], offset: 0, limit: 3, total: 8 },
-                loader,
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(3);
-            expect(pages[0].data).toEqual(["a", "b", "c"]);
-            expect(pages[1].data).toEqual(["d", "e"]);
-            expect(pages[2].data).toEqual(["f", "g"]);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should stop when next() returns null", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: [],
-                offset: 10,
-                limit: 10,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            const pages = [];
-            for await (const p of page.pages()) {
-                pages.push(p);
-            }
-            expect(pages).toHaveLength(2); // original + one fetched (which is empty/last)
-        });
-    });
-    describe("Symbol.asyncIterator", () => {
-        it("should iterate over items in single page", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a", "b", "c"], offset: 0, limit: 10, total: 3 },
-                loader: vi.fn(),
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual(["a", "b", "c"]);
-        });
-        it("should iterate over items across multiple pages", async () => {
-            const loader = vi.fn().mockResolvedValueOnce({
-                data: ["d", "e"],
-                offset: 3,
-                limit: 3,
-                total: 5,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 3 },
-                response: { data: ["a", "b", "c"], offset: 0, limit: 3, total: 5 },
-                loader,
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual(["a", "b", "c", "d", "e"]);
-        });
-        it("should handle empty pages gracefully", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            const items = [];
-            for await (const item of page) {
-                items.push(item);
-            }
-            expect(items).toEqual([]);
-        });
-        it("should work with complex objects", async () => {
-            const users = [
-                { id: 1, name: "Alice" },
-                { id: 2, name: "Bob" },
-            ];
-            const page = new OffsetPage({
-                params: {},
-                response: { data: users, offset: 0, limit: 10, total: 2 },
-                loader: vi.fn(),
-            });
-            const collected = [];
-            for await (const user of page) {
-                collected.push(user);
-            }
-            expect(collected).toEqual(users);
-            expect(collected[0]).toEqual({ id: 1, name: "Alice" });
-        });
-    });
-    describe("collect()", () => {
-        it("should collect all items from single page", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: ["a", "b", "c"], offset: 0, limit: 10, total: 3 },
-                loader: vi.fn(),
-            });
-            const items = await page.collect();
-            expect(items).toEqual(["a", "b", "c"]);
-        });
-        it("should collect all items from multiple pages", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({
-                data: ["d", "e", "f"],
-                offset: 3,
-                limit: 3,
-                total: 8,
-            })
-                .mockResolvedValueOnce({
-                data: ["g", "h"],
-                offset: 6,
-                limit: 3,
-                total: 8,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 3 },
-                response: { data: ["a", "b", "c"], offset: 0, limit: 3, total: 8 },
-                loader,
-            });
-            const items = await page.collect();
-            expect(items).toEqual(["a", "b", "c", "d", "e", "f", "g", "h"]);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should return empty array for empty page", async () => {
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader: vi.fn(),
-            });
-            const items = await page.collect();
-            expect(items).toEqual([]);
-        });
-        it("should preserve item order across pages", async () => {
-            const loader = vi
-                .fn()
-                .mockResolvedValueOnce({
-                data: [4, 5, 6],
-                offset: 3,
-                limit: 3,
-                total: 6,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 3 },
-                response: { data: [1, 2, 3], offset: 0, limit: 3, total: 6 },
-                loader,
-            });
-            const items = await page.collect();
-            expect(items).toEqual([1, 2, 3, 4, 5, 6]);
-        });
-    });
-    describe("edge cases", () => {
-        it("should handle consecutive next() calls correctly", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["next"],
-                offset: 10,
-                limit: 10,
-            });
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            const next1 = await page.next();
-            const next2 = await page.next();
-            expect(next1).not.toBe(null);
-            expect(next2).not.toBe(null);
-            expect(loader).toHaveBeenCalledTimes(2);
-        });
-        it("should handle loader throwing error", async () => {
-            const loader = vi.fn().mockRejectedValue(new Error("Database error"));
-            const page = new OffsetPage({
-                params: { offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            await expect(page.next()).rejects.toThrow("Database error");
-        });
-        it("should not call loader when last is true", async () => {
-            const loader = vi.fn();
-            const page = new OffsetPage({
-                params: {},
-                response: { data: [], offset: 0, limit: 10 },
-                loader,
-            });
-            await page.next();
-            expect(loader).not.toHaveBeenCalled();
-        });
-        it("should handle params with custom properties", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["b"],
-                offset: 10,
-                limit: 10,
-            });
-            const page = new OffsetPage({
-                params: { agentId: "agent-1", filter: "active", offset: 0, limit: 10 },
-                response: { data: ["a"], offset: 0, limit: 10 },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                agentId: "agent-1",
-                filter: "active",
-                offset: 10,
-                limit: 10,
-            });
-        });
-        it("should handle large offsets correctly", async () => {
-            const loader = vi.fn().mockResolvedValue({
-                data: ["x"],
-                offset: 1000010,
-                limit: 10,
-                total: 2000000,
-            });
-            const page = new OffsetPage({
-                params: { offset: 1000000, limit: 10 },
-                response: { data: ["a"], offset: 1000000, limit: 10, total: 2000000 },
-                loader,
-            });
-            await page.next();
-            expect(loader).toHaveBeenCalledWith({
-                offset: 1000010,
-                limit: 10,
-            });
-        });
-    });
-});

package/dist/api/pagination/base.d.ts

@@ -1,48 +0,0 @@
-export interface PageParamsBase {
-    /**
-     * Maximum number of items to return in a single page.
-     */
-    limit?: number;
-}
-/**
- * Generic page abstraction shared by all pagination modes.
- *
- * Loader: function that, given params, returns a page response.
- */
-export declare abstract class AbstractPage<T, TParams extends PageParamsBase, TResponse> implements AsyncIterable<T> {
-    protected readonly params: TParams;
-    protected readonly response: TResponse;
-    protected readonly loader: (params: TParams) => Promise<TResponse>;
-    constructor(args: {
-        params: TParams;
-        response: TResponse;
-        loader: (params: TParams) => Promise<TResponse>;
-    });
-    /**
-     * All items contained in this page.
-     */
-    abstract get items(): T[];
-    /**
-     * True if this is the last page in the sequence.
-     *
-     * When `last` is true, `next()` will return null.
-     */
-    abstract get last(): boolean;
-    /**
-     * Fetch the next page, or null if there is no next page.
-     */
-    abstract next(): Promise<this | null>;
-    /**
-     * Iterate over this page and all subsequent pages.
-     */
-    pages(): AsyncGenerator<this>;
-    /**
-     * Iterate over all items across this page and all subsequent pages.
-     */
-    [Symbol.asyncIterator](): AsyncGenerator<T>;
-    /**
-     * Collect all items from this page and all subsequent pages into an array.
-     */
-    collect(): Promise<T[]>;
-}
-//# sourceMappingURL=base.d.ts.map

package/dist/api/pagination/base.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/api/pagination/base.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,8BAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,SAAS,cAAc,EAAE,SAAS,CAC7E,YAAW,aAAa,CAAC,CAAC,CAAC;IAE3B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IACvC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;gBAEvD,IAAI,EAAE;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,SAAS,CAAC;QACpB,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;KACjD;IAMD;;OAEG;IACH,QAAQ,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAErC;;OAEG;IACI,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC;IAQpC;;OAEG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC;IAQlD;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;CAO9B"}

package/dist/api/pagination/base.js

@@ -1,45 +0,0 @@
-/**
- * Generic page abstraction shared by all pagination modes.
- *
- * Loader: function that, given params, returns a page response.
- */
-export class AbstractPage {
-    params;
-    response;
-    loader;
-    constructor(args) {
-        this.params = args.params;
-        this.response = args.response;
-        this.loader = args.loader;
-    }
-    /**
-     * Iterate over this page and all subsequent pages.
-     */
-    async *pages() {
-        let page = this;
-        while (page) {
-            yield page;
-            page = await page.next();
-        }
-    }
-    /**
-     * Iterate over all items across this page and all subsequent pages.
-     */
-    async *[Symbol.asyncIterator]() {
-        for await (const page of this.pages()) {
-            for (const item of page.items) {
-                yield item;
-            }
-        }
-    }
-    /**
-     * Collect all items from this page and all subsequent pages into an array.
-     */
-    async collect() {
-        const items = [];
-        for await (const item of this) {
-            items.push(item);
-        }
-        return items;
-    }
-}

package/dist/api/pagination/cursor.d.ts

@@ -1,44 +0,0 @@
-import { AbstractPage, type PageParamsBase } from "./base.js";
-export interface CursorPageParams extends PageParamsBase {
-    /**
-     * Pagination cursor returned from a previous page.
-     * If omitted, starts from the beginning of the collection.
-     */
-    cursor?: string;
-}
-export interface CursorPageResponse<T> {
-    data: T[];
-    /**
-     * Cursor for the next page, or null if there is no next page.
-     */
-    next: string | null;
-    /**
-     * True if this is the last page (no further pages).
-     */
-    last: boolean;
-}
-export declare class CursorPage<T, TParams extends CursorPageParams = CursorPageParams> extends AbstractPage<T, TParams, CursorPageResponse<T>> {
-    data: T[];
-    private readonly _next;
-    private readonly _last;
-    constructor(args: {
-        params: TParams;
-        response: CursorPageResponse<T>;
-        loader: (params: TParams) => Promise<CursorPageResponse<T>>;
-    });
-    /**
-     * All items contained in this page.
-     */
-    get items(): T[];
-    /**
-     * True if this is the last page in the sequence.
-     *
-     * When `last` is true, `next()` will return null.
-     */
-    get last(): boolean;
-    /**
-     * Fetch the next page, or null if there is no next page.
-     */
-    next(): Promise<this | null>;
-}
-//# sourceMappingURL=cursor.d.ts.map

package/dist/api/pagination/cursor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/api/pagination/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE3D,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,UAAU,CACrB,CAAC,EACD,OAAO,SAAS,gBAAgB,GAAG,gBAAgB,CACnD,SAAQ,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,IAAI,EAAE;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;KAC7D;IAOD;;OAEG;IACH,IAAI,KAAK,IAAI,CAAC,EAAE,CAEf;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,OAAO,CAIlB;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;CAuBnC"}