@greendrake/rpckit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +42 -2
  3. package/package.json +46 -3
  4. package/src/main.ts +43 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Eugene Greendrake
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,43 @@
1
- # Temporary Holding Version
1
+ # @greendrake/rpckit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Connects a data table to a server's paged list methods: it turns the table's search text, sort and range of rows into the arguments that every list method of the server takes. It is the client side of the paged-list convention of the Go `greendrake.nz/go/rpckit`.
4
+
5
+ ```sh
6
+ bun add @greendrake/rpckit vue
7
+ ```
8
+
9
+ `vue` is a peer dependency, and `@greendrake/ui-data` installs as a dependency. The package ships its TypeScript source, with no compiled output and no `.d.ts`, so the consuming app's bundler has to compile TypeScript, as Vite does.
10
+
11
+ ## Why
12
+
13
+ Every list method of a server that follows the convention takes the same arguments — `q`, `offset`, `limit`, `sort_by`, `sort_dir` — and answers `{ data, total }`. An `@greendrake/ui-data` table loads its rows through a `LoaderFunction`, which is called with the table's own values: the search text, the sort, a range of rows.
14
+
15
+ Without this package, every table of a dashboard translates one into the other by hand, and every table with a filter wires its own re-fetch for when the filter changes. This package writes both once, in `listLoader` and `narrowedList`.
16
+
17
+ ## Trade-offs
18
+
19
+ - **Tied to the convention.** A server whose lists take other arguments, or answer another shape, gets nothing from this package. The convention pages by offset and limit, and there is no cursor.
20
+ - **Tied to `@greendrake/ui-data` and Vue.** It produces that package's `LoaderFunction`, and `narrowedList` returns a Vue `computed`.
21
+
22
+ ## Surface
23
+
24
+ The package makes no calls itself. You pass it the function that calls your server, so it works over any transport.
25
+
26
+ - `PageArgs` is `{ q?, offset?, limit?, sort_by?, sort_dir? }`, the arguments every paged list method parses. A method that honours only some of them ignores the rest.
27
+ - `listLoader<T>(fetch)` makes an `@greendrake/ui-data` `LoaderFunction<T>` from a list call, `(args: PageArgs, background: boolean) => Promise<LoaderResponse<T>>`. The table's search text goes as `q`. Its order, when it has one, goes as `sort_by` and `sort_dir`. A method's own filters are added inside `fetch`. The `background` flag is passed on unchanged — here to `listOrders`, the app's own call of its `admin.order.list` method:
28
+
29
+ ```ts
30
+ const loader = listLoader((args, background) => listOrders({ ...args, status }, background))
31
+ ```
32
+
33
+ The loader does not touch the table's `loading` ref. The table shows its spinner itself while the viewport overlaps rows not yet loaded.
34
+
35
+ - `narrowedList<N, T>(narrowing, fetch)` is for a list filtered by arguments of the method's own. It returns `{ filters, loader }`, as a table takes them. `filters` is a Vue `computed` of `narrowing()`: the current arguments, with `undefined` for one not given. Pass it as the table's `filters`, and a change to any of them re-fetches. `loader` is a `listLoader`. For each page it calls `fetch` with the page arguments and the value of `narrowing()` at that moment:
36
+
37
+ ```ts
38
+ const status = ref<'' | 'open' | 'closed'>('')
39
+ const { filters, loader } = narrowedList(
40
+ () => ({ status: status.value || undefined }),
41
+ (args, background) => listOrders(args, background)
42
+ )
43
+ ```
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@greendrake/rpckit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "The client half of the Go greendrake.nz/go/rpckit paged-list convention: its list arguments, and the adapter feeding them from @greendrake/ui-data's tables",
5
+ "license": "MIT",
6
+ "author": "Eugene Greendrake <eugene@greendrake.nz>",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/greendrake/lib.git",
10
+ "directory": "rpckit"
11
+ },
12
+ "homepage": "https://github.com/greendrake/lib/tree/main/rpckit#readme",
13
+ "bugs": {
14
+ "url": "https://github.com/greendrake/lib/issues"
15
+ },
16
+ "type": "module",
17
+ "main": "src/main.ts",
18
+ "types": "src/main.ts",
19
+ "exports": {
20
+ ".": {
21
+ "types": "./src/main.ts",
22
+ "default": "./src/main.ts"
23
+ }
24
+ },
25
+ "files": [
26
+ "src"
27
+ ],
28
+ "sideEffects": false,
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "prettier": "@greendrake/dev-config/prettier",
33
+ "dependencies": {
34
+ "@greendrake/ui-data": "^0.10.0"
35
+ },
36
+ "peerDependencies": {
37
+ "vue": "^3.5.34"
38
+ },
39
+ "devDependencies": {
40
+ "@greendrake/dev-config": "0.8.0",
41
+ "@types/bun": "^1.3.5",
42
+ "typescript": "6.0.3",
43
+ "vue": "^3.5.34",
44
+ "vue-tsc": "^2.2.0"
45
+ },
46
+ "scripts": {
47
+ "check": "vue-tsc --noEmit"
48
+ }
6
49
  }
package/src/main.ts ADDED
@@ -0,0 +1,43 @@
1
+ import { computed, type ComputedRef, type Ref } from 'vue'
2
+ import type { Filters, LoaderFunction, LoaderParams, LoaderResponse, SortDir } from '@greendrake/ui-data'
3
+
4
+ // The arguments of every paged list method the Go rpckit's PageArgs parses:
5
+ // the search text as q, the window, and the order as sort_by / sort_dir. A
6
+ // method honouring only some of them ignores the rest.
7
+ export type PageArgs = {
8
+ q?: string
9
+ offset?: number
10
+ limit?: number
11
+ sort_by?: string
12
+ sort_dir?: SortDir
13
+ }
14
+
15
+ // A table's LoaderFunction over a paged list call: its params in the list
16
+ // arguments' terms — the order only when the table has one. A method's filters
17
+ // of its own ride the `fetch` closure, and so does what a background read
18
+ // costs, the flag handed on verbatim:
19
+ // listLoader((args, background) => listOrders({ ...args, status }, background))
20
+ // The table's loading ref is not touched: the table shows its spinner itself
21
+ // while the viewport overlaps rows not yet loaded.
22
+ export const listLoader =
23
+ <T>(fetch: (args: PageArgs, background: boolean) => Promise<LoaderResponse<T>>) =>
24
+ (params: LoaderParams, _loading: Ref<boolean>, background: boolean): Promise<LoaderResponse<T>> =>
25
+ fetch(
26
+ {
27
+ offset: params.offset,
28
+ limit: params.limit,
29
+ ...(params.text ? { q: params.text } : {}),
30
+ ...(params.sort ? { sort_by: params.sort.by, sort_dir: params.sort.dir } : {})
31
+ },
32
+ background
33
+ )
34
+
35
+ // A paged list call narrowed by arguments of the method's own, as a table
36
+ // takes it: the filters, which are those arguments — so a change of any
37
+ // re-fetches — and the loader asking the call with them as they then stand.
38
+ // `narrowing` reads them, undefined for one not given:
39
+ // const { filters, loader } = narrowedList(() => ({ status: status.value || undefined }), (args, background) => listOrders(args, background))
40
+ export const narrowedList = <N extends Filters, T>(narrowing: () => N, fetch: (args: PageArgs & N, background: boolean) => Promise<LoaderResponse<T>>): { filters: ComputedRef<N>; loader: LoaderFunction<T> } => ({
41
+ filters: computed(narrowing),
42
+ loader: listLoader((args, background) => fetch({ ...args, ...narrowing() }, background))
43
+ })