@streamscloud/kit 0.55.1 → 0.56.0

package/dist/core/data-loaders/cursor-data-loader-with-search.svelte.d.ts

@@ -2,13 +2,14 @@ import { ContinuationToken, type CursorResult } from '..';
 import type { IDataLoader } from './data-loader';
 export declare class CursorDataLoaderWithSearch<T> implements IDataLoader<T> {
     items: T[];
-    private continuationToken;
+    private _continuationToken;
     private _searchString;
-    private loadPage;
-    private pending;
-    private generation;
-    private searchStringMinLength;
+    private _loadPage;
+    private _pending;
+    private _generation;
+    private _searchStringMinLength;
     private _loading;
+    private _failed;
     constructor(init: {
         loadPage: (continuationToken: ContinuationToken, searchString: string) => Promise<CursorResult<T> | null>;
         searchStringMinLength?: number;
@@ -16,6 +17,7 @@ export declare class CursorDataLoaderWithSearch<T> implements IDataLoader<T> {
     get searchString(): string;
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset(): Promise<void>;
     updateSearchString: (searchString: string | null) => void;

package/dist/core/data-loaders/cursor-data-loader-with-search.svelte.js

@@ -2,17 +2,18 @@ import { ContinuationToken } from '..';
 import { Utils } from '../utils';
 export class CursorDataLoaderWithSearch {
     items = $state.raw([]);
-    continuationToken = $state.raw(ContinuationToken.init());
+    _continuationToken = $state.raw(ContinuationToken.init());
     _searchString = $state.raw('');
-    loadPage;
-    pending = null;
-    generation = 0;
-    searchStringMinLength = 1;
+    _loadPage;
+    _pending = null;
+    _generation = 0;
+    _searchStringMinLength = 1;
     _loading = $state(false);
+    _failed = $state(false);
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
         if (init.searchStringMinLength !== undefined) {
-            this.searchStringMinLength = init.searchStringMinLength;
+            this._searchStringMinLength = init.searchStringMinLength;
         }
         this.updateSearchString = Utils.debounce(this.updateSearchString, 400);
     }
@@ -25,33 +26,36 @@ export class CursorDataLoaderWithSearch {
     get initialLoading() {
         return this._loading && this.items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this.pending) {
-            return this.pending;
+        if (this._pending) {
+            return this._pending;
         }
-        if (!this.continuationToken.canLoadMore) {
+        if (!this._continuationToken.canLoadMore) {
             return [];
         }
         this._loading = true;
         const pending = this.runLoad();
-        this.pending = pending;
+        this._pending = pending;
         try {
             return await pending;
         }
         finally {
             // a concurrent reset() may have installed a newer load — leave that one alone
-            if (this.pending === pending) {
-                this.pending = null;
+            if (this._pending === pending) {
+                this._pending = null;
                 this._loading = false;
             }
         }
     };
     async reset() {
-        this.generation++;
-        this.pending = null;
+        this._generation++;
+        this._pending = null;
         this._loading = false;
         this.items = [];
-        this.continuationToken = ContinuationToken.init();
+        this._continuationToken = ContinuationToken.init();
         await this.loadMore();
     }
     updateSearchString = (searchString) => {
@@ -67,22 +71,28 @@ export class CursorDataLoaderWithSearch {
         }
     };
     runLoad = async () => {
-        const generation = this.generation;
+        const generation = this._generation;
         const search = this.isSearchStringEffective(this._searchString) ? this._searchString : '';
+        this._failed = false;
         try {
-            const result = (await this.loadPage(this.continuationToken, search)) ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            const page = await this._loadPage(this._continuationToken, search);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
-            this.continuationToken = result.continuationToken;
+            const result = page ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            this._failed = page === null;
+            this._continuationToken = result.continuationToken;
             this.items = [...this.items, ...result.items];
             return result.items;
         }
         catch (error) {
             console.error('CursorDataLoaderWithSearch: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
     };
-    isSearchStringEffective = (searchString) => searchString && searchString.length >= this.searchStringMinLength;
+    isSearchStringEffective = (searchString) => searchString && searchString.length >= this._searchStringMinLength;
 }

package/dist/core/data-loaders/cursor-data-loader.svelte.d.ts

@@ -3,15 +3,17 @@ import type { IDataLoader } from './data-loader';
 export declare class CursorDataLoader<T> implements IDataLoader<T> {
     items: T[];
     continuationToken: ContinuationToken;
-    private loadPage;
-    private pending;
-    private generation;
+    private _loadPage;
+    private _pending;
+    private _generation;
     private _loading;
+    private _failed;
     constructor(init: {
         loadPage: (continuationToken: ContinuationToken) => Promise<CursorResult<T> | null>;
     });
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset(): Promise<void>;
     private runLoad;

package/dist/core/data-loaders/cursor-data-loader.svelte.js

@@ -2,12 +2,13 @@ import { ContinuationToken } from '..';
 export class CursorDataLoader {
     items = $state.raw([]);
     continuationToken = $state.raw(ContinuationToken.init());
-    loadPage;
-    pending = null;
-    generation = 0;
+    _loadPage;
+    _pending = null;
+    _generation = 0;
     _loading = $state(false);
+    _failed = $state(false);
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
     }
     get loading() {
         return this._loading;
@@ -15,49 +16,58 @@ export class CursorDataLoader {
     get initialLoading() {
         return this._loading && this.items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this.pending) {
-            return this.pending;
+        if (this._pending) {
+            return this._pending;
         }
         if (!this.continuationToken.canLoadMore) {
             return [];
         }
         this._loading = true;
         const pending = this.runLoad();
-        this.pending = pending;
+        this._pending = pending;
         try {
             return await pending;
         }
         finally {
             // a concurrent reset() may have installed a newer load — leave that one alone
-            if (this.pending === pending) {
-                this.pending = null;
+            if (this._pending === pending) {
+                this._pending = null;
                 this._loading = false;
             }
         }
     };
     async reset() {
-        this.generation++;
-        this.pending = null;
+        this._generation++;
+        this._pending = null;
         this._loading = false;
         this.items = [];
         this.continuationToken = ContinuationToken.init();
         await this.loadMore();
     }
     runLoad = async () => {
-        const generation = this.generation;
+        const generation = this._generation;
+        this._failed = false;
         try {
-            const result = (await this.loadPage(this.continuationToken)) ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            const page = await this._loadPage(this.continuationToken);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
+            const result = page ?? { items: [], continuationToken: ContinuationToken.preventLoading() };
+            this._failed = page === null;
             this.continuationToken = result.continuationToken;
             this.items = [...this.items, ...result.items];
             return result.items;
         }
         catch (error) {
             console.error('CursorDataLoader: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
     };

package/dist/core/data-loaders/data-loader.d.ts

@@ -3,5 +3,7 @@ export interface IDataLoader<T> {
     loading: boolean;
     /** Loading with nothing to show yet — first load, or a reload after the list was cleared by a reset. */
     initialLoading: boolean;
+    /** The last attempt did not deliver a page, whether it returned nothing or threw; cleared when the next attempt starts. */
+    failed: boolean;
     loadMore: () => Promise<T[]>;
 }

package/dist/core/data-loaders/index.d.ts

@@ -1,4 +1,5 @@
 export type { IDataLoader } from './data-loader';
 export { CursorDataLoader } from './cursor-data-loader.svelte';
 export { CursorDataLoaderWithSearch } from './cursor-data-loader-with-search.svelte';
+export { KeyedCursorDataLoader } from './keyed-cursor-data-loader.svelte';
 export { PageDataLoader } from './page-data-loader.svelte';

package/dist/core/data-loaders/index.js

@@ -1,4 +1,5 @@
 // Data loaders
 export { CursorDataLoader } from './cursor-data-loader.svelte';
 export { CursorDataLoaderWithSearch } from './cursor-data-loader-with-search.svelte';
+export { KeyedCursorDataLoader } from './keyed-cursor-data-loader.svelte';
 export { PageDataLoader } from './page-data-loader.svelte';

package/dist/core/data-loaders/keyed-cursor-data-loader.svelte.d.ts

@@ -0,0 +1,28 @@
+import { ContinuationToken, type CursorResult } from '..';
+export declare class KeyedCursorDataLoader<T> {
+    private _loaders;
+    private _loaded;
+    private _pending;
+    private _loadPage;
+    private _loadAlongside;
+    constructor(init: {
+        loadPage: (key: string, continuationToken: ContinuationToken) => Promise<CursorResult<T> | null>;
+        /** Started with the key's first page and awaited by `ensureLoaded`; its outcome never reaches `isLoaded`. */
+        loadAlongside?: (key: string) => Promise<void>;
+    });
+    items: (key?: string) => T[];
+    loading: (key?: string) => boolean;
+    initialLoading: (key?: string) => boolean;
+    canLoadMore: (key?: string) => boolean;
+    /** False until the key's first page loaded without failing, so a failed load can be retried; a later failed page never clears it. */
+    isLoaded: (key?: string) => boolean;
+    /** Loads the key's first page once; concurrent and repeat calls share that load's promise. */
+    ensureLoaded: (key?: string) => Promise<void>;
+    loadMore: (key?: string) => Promise<T[]>;
+    /** Drops the key's pages and loads them again from the first one. */
+    reload: (key?: string) => Promise<void>;
+    private startLoad;
+    private runLoad;
+    private runAlongside;
+    private loaderFor;
+}

package/dist/core/data-loaders/keyed-cursor-data-loader.svelte.js

@@ -0,0 +1,66 @@
+import { ContinuationToken } from '..';
+import { CursorDataLoader } from './cursor-data-loader.svelte';
+export class KeyedCursorDataLoader {
+    _loaders = {};
+    _loaded = $state.raw({});
+    _pending = {};
+    _loadPage;
+    _loadAlongside;
+    constructor(init) {
+        this._loadPage = init.loadPage;
+        this._loadAlongside = init.loadAlongside;
+    }
+    items = (key = '') => this.loaderFor(key).items;
+    loading = (key = '') => this.loaderFor(key).loading;
+    initialLoading = (key = '') => this.loaderFor(key).initialLoading;
+    canLoadMore = (key = '') => this.loaderFor(key).continuationToken.canLoadMore;
+    /** False until the key's first page loaded without failing, so a failed load can be retried; a later failed page never clears it. */
+    isLoaded = (key = '') => this._loaded[key] === true;
+    /** Loads the key's first page once; concurrent and repeat calls share that load's promise. */
+    ensureLoaded = (key = '') => {
+        if (this._loaded[key]) {
+            return Promise.resolve();
+        }
+        return this._pending[key] ?? this.startLoad(key);
+    };
+    loadMore = (key = '') => this.loaderFor(key).loadMore();
+    /** Drops the key's pages and loads them again from the first one. */
+    reload = (key = '') => {
+        this._loaded = { ...this._loaded, [key]: false };
+        return this.startLoad(key);
+    };
+    startLoad = async (key) => {
+        const pending = this.runLoad(key);
+        this._pending[key] = pending;
+        try {
+            await pending;
+        }
+        finally {
+            // a concurrent reload() may have installed a newer load — leave that one alone
+            if (this._pending[key] === pending) {
+                this._pending[key] = undefined;
+            }
+        }
+    };
+    runLoad = async (key) => {
+        const loader = this.loaderFor(key);
+        const alongside = this.runAlongside(key);
+        await loader.reset();
+        this._loaded = { ...this._loaded, [key]: !loader.failed };
+        await alongside;
+    };
+    runAlongside = async (key) => {
+        try {
+            await this._loadAlongside?.(key);
+        }
+        catch (error) {
+            console.error('KeyedCursorDataLoader: failed to load alongside the page', error);
+        }
+    };
+    loaderFor = (key) => {
+        if (!this._loaders[key]) {
+            this._loaders[key] = new CursorDataLoader({ loadPage: (continuationToken) => this._loadPage(key, continuationToken) });
+        }
+        return this._loaders[key];
+    };
+}

package/dist/core/data-loaders/page-data-loader.svelte.d.ts

@@ -2,11 +2,12 @@ import type { IDataLoader } from './data-loader';
 export declare class PageDataLoader<T> implements IDataLoader<T> {
     private _items;
     private _loading;
-    private canLoadMore;
-    private perPage;
-    private loadPage;
-    private pageNumber;
-    private generation;
+    private _failed;
+    private _canLoadMore;
+    private _perPage;
+    private _loadPage;
+    private _pageNumber;
+    private _generation;
     constructor(init: {
         loadPage: (page: number, perPage: number) => Promise<T[]>;
         perPage?: number;
@@ -14,6 +15,7 @@ export declare class PageDataLoader<T> implements IDataLoader<T> {
     get items(): T[];
     get loading(): boolean;
     get initialLoading(): boolean;
+    get failed(): boolean;
     loadMore: () => Promise<T[]>;
     reset: () => Promise<void>;
 }

package/dist/core/data-loaders/page-data-loader.svelte.js

@@ -1,15 +1,16 @@
 export class PageDataLoader {
     _items = $state.raw([]);
     _loading = $state(false);
-    canLoadMore = $state(true);
-    perPage = 20;
-    loadPage;
-    pageNumber = 1;
-    generation = 0;
+    _failed = $state(false);
+    _canLoadMore = $state(true);
+    _perPage = 20;
+    _loadPage;
+    _pageNumber = 1;
+    _generation = 0;
     constructor(init) {
-        this.loadPage = init.loadPage;
+        this._loadPage = init.loadPage;
         if (init.perPage) {
-            this.perPage = init.perPage;
+            this._perPage = init.perPage;
         }
     }
     get items() {
@@ -21,39 +22,46 @@ export class PageDataLoader {
     get initialLoading() {
         return this._loading && this._items.length === 0;
     }
+    get failed() {
+        return this._failed;
+    }
     loadMore = async () => {
-        if (this._loading || !this.canLoadMore) {
+        if (this._loading || !this._canLoadMore) {
             return [];
         }
-        const generation = this.generation;
+        const generation = this._generation;
         this._loading = true;
+        this._failed = false;
         try {
-            const items = await this.loadPage(this.pageNumber, this.perPage);
+            const items = await this._loadPage(this._pageNumber, this._perPage);
             // a reset() mid-load bumps the generation — drop the stale page instead of appending it to the cleared list
-            if (generation !== this.generation) {
+            if (generation !== this._generation) {
                 return [];
             }
-            this.pageNumber++;
-            this.canLoadMore = items.length === this.perPage;
+            this._pageNumber++;
+            this._canLoadMore = items.length === this._perPage;
             this._items = [...this._items, ...items];
             return items;
         }
         catch (error) {
             console.error('PageDataLoader: failed to load page', error);
+            if (generation === this._generation) {
+                this._failed = true;
+            }
             return [];
         }
         finally {
-            if (generation === this.generation) {
+            if (generation === this._generation) {
                 this._loading = false;
             }
         }
     };
     reset = async () => {
-        this.generation++;
+        this._generation++;
         this._loading = false;
-        this.pageNumber = 1;
+        this._pageNumber = 1;
         this._items = [];
-        this.canLoadMore = true;
+        this._canLoadMore = true;
         await this.loadMore();
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/kit",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "author": "StreamsCloud",
   "repository": {
     "type": "git",