@trellisjs/plugin-datasource 0.1.0-alpha.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TrellisJS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @trellisjs/plugin-datasource
+
+Datasource abstraction for Trellis data tables, with built-in static (local) and remote (HTTP) implementations.
+
+## Installation
+
+```bash
+npm install @trellisjs/plugin-datasource
+```
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `createStaticDatasource<T>(data, options?)` | Local datasource that performs sorting, filtering, and pagination in memory. |
+| `createRemoteDatasource<T>(options)` | HTTP datasource that sends standardized queries to a backend API. |
+| `buildQueryFromState(api)` | Builds a `TrellisQuery` from the current Trellis state (sorting, filtering, pagination). |
+| `TrellisQuery` | Query shape sent to `datasource.fetch()`. |
+| `TrellisResponse<T>` | Expected response shape: `{ data, total, filtered }`. |
+| `TrellisDatasource<T>` | Interface: `{ fetch(query): Promise<TrellisResponse<T>> }`. |
+
+## Usage
+
+### Static Datasource (Client-Side)
+
+```ts
+import { createStaticDatasource } from '@trellisjs/plugin-datasource';
+
+const ds = createStaticDatasource([
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 },
+]);
+
+const result = await ds.fetch({
+  page: 1,
+  pageSize: 10,
+  sort: [{ columnId: 'age', direction: 'asc' }],
+  filter: { global: 'ali' },
+});
+// result.data   --> [{ name: 'Alice', age: 30 }]
+// result.total  --> 2
+// result.filtered --> 1
+```
+
+### Remote Datasource (Server-Side)
+
+```ts
+import { createRemoteDatasource } from '@trellisjs/plugin-datasource';
+
+const ds = createRemoteDatasource({
+  url: '/api/users',
+  method: 'POST',                 // default
+  headers: { Authorization: 'Bearer ...' },
+  transformQuery: (q) => ({       // adapt to your API contract
+    page: q.page,
+    per_page: q.pageSize,
+    sort_by: q.sort?.[0]?.columnId,
+    sort_dir: q.sort?.[0]?.direction,
+  }),
+  transformResponse: (raw) => ({   // adapt response to TrellisResponse
+    data: raw.items,
+    total: raw.total_count,
+    filtered: raw.filtered_count,
+  }),
+});
+
+const result = await ds.fetch({ page: 1, pageSize: 20 });
+```
+
+### Build Query from Trellis State
+
+```ts
+import { buildQueryFromState } from '@trellisjs/plugin-datasource';
+
+const query = buildQueryFromState(api);
+// { page, pageSize, sort?, filter? }
+```
+
+## TrellisQuery Shape
+
+```ts
+interface TrellisQuery {
+  page: number;                          // 1-based
+  pageSize: number;
+  sort?: { columnId: string; direction: 'asc' | 'desc' }[];
+  filter?: { global?: string; columns?: Record<string, unknown> };
+}
+```
+
+## TrellisResponse Shape
+
+```ts
+interface TrellisResponse<T> {
+  data: T[];       // rows for the current page
+  total: number;   // total rows (unfiltered)
+  filtered: number; // total rows after filtering
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trellisjs/plugin-datasource",
-  "version": "0.1.0-alpha.1",
+  "version": "1.0.0",
   "description": "資料源插件 — 支援靜態資料與遠端 API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -20,22 +20,27 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
-    "@trellisjs/core": "workspace:*"
+    "@trellisjs/core": "0.1.0"
   },
   "devDependencies": {
-    "@trellisjs/core": "workspace:*",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^3.1.0",
+    "@trellisjs/core": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cluion/trellis.git",
+    "directory": "packages/plugin-datasource"
   },
   "license": "MIT",
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}