[add] Usage document of Buffer & Stream List

TechQuery · TechQuery · commit 947b3fbf7023 · 2022-08-16T20:01:44.000+08:00
[fix] Page Size mutation logic
diff --git a/ReadMe.md b/ReadMe.md
@@ -12,7 +12,9 @@ Just define your **Data models** & **Client HTTP methods**, then leave rest of t
 
 ## Usage
 
-### `model/client.ts`
+### Simple List
+
+#### `model/client.ts`
 
 ```javascript
 import { HTTPClient } from 'koajax';
@@ -23,7 +25,7 @@ export const client = new HTTPClient({
 });
 ```
 
-### `model/Repository.ts`
+#### `model/Repository.ts`
 
 ```typescript
 import { buildURLData } from 'web-utility';
@@ -37,7 +39,7 @@ export class RepositoryModel extends ListModel<Repository> {
     client = client;
     baseURI = 'orgs/idea2app/repos';
 
-    async loadPage(page: number, per_page: number) {
+    protected async loadPage(page: number, per_page: number) {
         const { body } = await this.client.get<Repository[]>(
             `${this.baseURI}?${buildURLData({ page, per_page })}`
         );
@@ -48,7 +50,7 @@ export class RepositoryModel extends ListModel<Repository> {
 export default new RepositoryModel();
 ```
 
-### `page/Repository.tsx`
+#### `page/Repository.tsx`
 
 Use [WebCell][6] as an Example
 
@@ -88,6 +90,89 @@ export class RepositoryPage extends WebCell() {
 }
 ```
 
+### Preload List
+
+#### `model/Repository.ts`
+
+```diff
+import { buildURLData } from 'web-utility';
+-import { ListModel } from 'mobx-restful';
++import { BufferListModel } from 'mobx-restful';
+
+import { client } from './client';
+
+export type Repository = Record<'full_name' | 'html_url', string>;
+
+-export class RepositoryModel extends ListModel<Repository> {
++export class RepositoryModel extends BufferListModel<Repository>() {
+    client = client;
+    baseURI = 'orgs/idea2app/repos';
+
+    protected async loadPage(page: number, per_page: number) {
+        const { body } = await this.client.get<Repository[]>(
+            `${this.baseURI}?${buildURLData({ page, per_page })}`
+        );
+        return { pageData: body };
+    }
+}
+
+export default new RepositoryModel();
+```
+
+### Multiple Source List
+
+#### `model/Repository.ts`
+
+```diff
+-import { buildURLData } from 'web-utility';
++import { buildURLData, mergeStream } from 'web-utility';
+-import { ListModel } from 'mobx-restful';
++import { StreamListModel } from 'mobx-restful';
+
+import { client } from './client';
+
+export type Repository = Record<'full_name' | 'html_url', string>;
+
+-export class RepositoryModel extends ListModel<Repository> {
++export class RepositoryModel extends StreamListModel<Repository>() {
+    client = client;
+-    baseURI = 'orgs/idea2app/repos';
+
+-    protected async loadPage(page: number, per_page: number) {
+-        const { body } = await this.client.get<Repository[]>(
+-            `${this.baseURI}?${buildURLData({ page, per_page })}`
+-        );
+-        return { pageData: body };
+-    }
++    protected openStream() {
++        return mergeStream(
++            async function* () {
++                for (let i = 1; ; i++) {
++                    const { body } = await client.get<Repository[]>(
++                        'orgs/idea2app/repos?page=' + i
++                    );
++                    if (!body[0]) break;
++
++                    yield* body;
++                }
++            },
++            async function* () {
++                for (let i = 1; ; i++) {
++                    const { body } = await client.get<Repository[]>(
++                        'users/TechQuery/repos?page=' + i
++                    );
++                    if (!body[0]) break;
++
++                    yield* body;
++                }
++            }
++        );
++    }
+}
+
+export default new RepositoryModel();
+```
+
 ## Scaffold
 
 -   Progressive Web App (React): https://github.com/idea2app/React-MobX-Bootstrap-ts
diff --git a/package.json b/package.json
@@ -41,7 +41,7 @@
         "@parcel/packager-ts": "^2.7.0",
         "@parcel/transformer-typescript-types": "^2.7.0",
         "@types/jest": "^28.1.7",
-        "@types/node": "^14.18.23",
+        "@types/node": "^14.18.24",
         "dotenv": "^16.0.1",
         "husky": "^8.0.1",
         "jest": "^28.1.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/source/List.ts b/source/List.ts
@@ -89,6 +89,8 @@ export abstract class ListModel<
             pageSize,
             filter
         );
+        this.pageSize = pageSize;
+
         const list = [...this.pageList];
         list[pageIndex - 1] = pageData;
         this.pageList = list;
@@ -194,6 +196,8 @@ export abstract class StreamList<
     D extends DataObject,
     F extends NewData<D> = NewData<D>
 > extends ListModel<D, F> {
+    baseURI = '';
+
     protected stream?: AsyncGenerator<D, void, D>;
     protected abstract openStream(filter: F): AsyncGenerator<D, void, D>;
 
@@ -218,22 +222,24 @@ export function StreamListModel<
             pageSize: number,
             filter: F
         ) {
-            const newPageCount = pageIndex - this.pageList.length;
+            const { allItems } = this,
+                newList: D[] = [];
+            const newCount = pageIndex * pageSize - allItems.length;
 
             this.stream ||= this.openStream(filter);
 
-            for (let i = 0; i < newPageCount; i++) {
-                const pageData: D[] = [];
+            for (let i = 0; i < newCount; i++) {
+                const { done, value } = await this.stream.next();
 
-                for (let j = 0; j < pageSize; j++) {
-                    const { done, value } = await this.stream.next();
+                if (done) break;
 
-                    if (done) break;
-
-                    pageData.push(value as D);
-                }
-                this.pageList = [...this.pageList, pageData];
+                newList.push(value as D);
             }
+
+            this.pageList = splitArray(
+                [...this.allItems, ...newList],
+                pageSize
+            );
             return { pageData: this.pageList[pageIndex - 1] };
         }
     }
diff --git a/test/List.spec.ts b/test/List.spec.ts
@@ -3,10 +3,10 @@ import { isEmpty, buildURLData, mergeStream } from 'web-utility';
 import { ListModel, StreamListModel } from '../source/List';
 import { client } from './service';
 
+type Repository = Record<'full_name' | 'html_url', string>;
+
 describe('List model', () => {
     describe('Single List model', () => {
-        type Repository = Record<'full_name' | 'html_url', string>;
-
         class RepositoryModel extends ListModel<Repository> {
             client = client;
             baseURI = 'orgs/idea2app/repos';
@@ -98,48 +98,62 @@ describe('List model', () => {
     });
 
     describe('Multiple List model', () => {
-        type User = Record<'name', string>;
-
-        class UserModel extends StreamListModel<User>() {
+        class RepositoryModel extends StreamListModel<Repository>() {
             client = client;
-            baseURI = 'user';
 
             protected openStream() {
                 return mergeStream(
                     async function* () {
-                        yield* new Array<User>(3).fill({ name: 'Ukrainian' });
+                        for (let i = 1; ; i++) {
+                            const { body } = await client.get<Repository[]>(
+                                'orgs/idea2app/repos?page=' + i
+                            );
+                            if (!body[0]) break;
+
+                            yield* body;
+                        }
                     },
                     async function* () {
-                        yield* new Array<User>(3).fill({ name: 'Russian' });
+                        for (let i = 1; ; i++) {
+                            const { body } = await client.get<Repository[]>(
+                                'users/TechQuery/repos?page=' + i
+                            );
+                            if (!body[0]) break;
+
+                            yield* body;
+                        }
                     }
                 );
             }
         }
-        const store = new UserModel();
+        const store = new RepositoryModel();
 
         it('should load a Page with items in every stream', async () => {
             const list = await store.getList({}, 1, 3);
 
-            expect(list).toEqual([
-                { name: 'Ukrainian' },
-                { name: 'Russian' },
-                { name: 'Ukrainian' }
-            ]);
+            expect(
+                list.map(({ full_name }) => full_name.split('/')[0])
+            ).toEqual(['idea2app', 'TechQuery', 'idea2app']);
         });
 
-        it('should load all pages before current page', async () => {
+        it('should load all items before current page', async () => {
             store.clear();
 
             expect(store.pageList).toHaveLength(0);
 
-            const list = await store.getList({}, 2, 3);
+            const list = await store.getList({}, 2, 4);
 
-            expect(list).toEqual([
-                { name: 'Russian' },
-                { name: 'Ukrainian' },
-                { name: 'Russian' }
-            ]);
-            expect(store.allItems).toHaveLength(6);
+            expect(
+                list.map(({ full_name }) => full_name.split('/')[0])
+            ).toEqual(['idea2app', 'TechQuery', 'idea2app', 'TechQuery']);
+
+            expect(
+                store.pageList[0].map(
+                    ({ full_name }) => full_name.split('/')[0]
+                )
+            ).toEqual(['idea2app', 'TechQuery', 'idea2app', 'TechQuery']);
+
+            expect(store.allItems).toHaveLength(8);
         });
     });
 });
