@shivaedev/admin 0.16.0 → 0.16.2
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.
- package/CHANGELOG.md +15 -0
- package/README.md +52 -3
- package/dist/jobs/page.d.ts +33 -33
- package/package.json +8 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.16.2 - 2026-11-01
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Update `@shivaedev/identity` from 0.14.0 to 0.15.0.
|
|
8
|
+
- Update `@shivaedev/jobs` from 0.28.2 to 0.28.3.
|
|
9
|
+
- Update `@shivaedev/react` from 0.30.1 to 0.31.0.
|
|
10
|
+
|
|
11
|
+
## 0.16.1 - 2026-10-31
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- Update `@shivaedev/identity` from 0.13.0 to 0.14.0.
|
|
16
|
+
- Update `@shivaedev/jobs` from 0.28.1 to 0.28.2.
|
|
17
|
+
|
|
3
18
|
## 0.16.0 - 2026-10-31
|
|
4
19
|
|
|
5
20
|
### Added
|
package/README.md
CHANGED
|
@@ -28,6 +28,8 @@ An admin page is a native `@shivaedev/contract` contract plus a stable id, route
|
|
|
28
28
|
|
|
29
29
|
Declare each page's queries, commands and streams with `@shivaedev/contract`, then pass its native contract to `adminPage`. The stable id identifies the page at server registration; route metadata belongs to the application's view. Author RPC namespaces in the contract name, such as `admin.jobs`.
|
|
30
30
|
|
|
31
|
+
For a wholly admin-only jobs feature, put this browser-safe declaration in `src/modules/admin/jobs/pages.ts`:
|
|
32
|
+
|
|
31
33
|
```ts
|
|
32
34
|
import { Schema } from "effect";
|
|
33
35
|
import { JobsPermission } from "@shivaedev/admin/permissions.ts";
|
|
@@ -40,18 +42,18 @@ const Failed = query("failed", {
|
|
|
40
42
|
reads: () => [],
|
|
41
43
|
success: Schema.Array(Schema.String),
|
|
42
44
|
});
|
|
43
|
-
const Jobs = adminPage({
|
|
45
|
+
export const Jobs = adminPage({
|
|
44
46
|
id: "jobs",
|
|
45
47
|
permission: JobsPermission,
|
|
46
48
|
route: { path: "/admin/jobs", title: "Jobs" },
|
|
47
49
|
contract: contract("admin.jobs", { queries: [Failed] }),
|
|
48
50
|
});
|
|
49
|
-
const Admin = adminRegistry(Jobs);
|
|
51
|
+
export const Admin = adminRegistry(Jobs);
|
|
50
52
|
```
|
|
51
53
|
|
|
52
54
|
`Jobs.contract` keeps the native `.declaration` and `.application.toLayer` APIs. `adminRegistry(...pages)` returns `pages` and a native `group`. Duplicate page ids, route paths and RPC tags, including generated subscriptions, fail when the registry is created.
|
|
53
55
|
|
|
54
|
-
Register server handler Layers by page id
|
|
56
|
+
Register server handler Layers by page id in `src/modules/admin/jobs/server/registration.ts`, importing `Admin` and `Jobs` from that module's `pages.ts`:
|
|
55
57
|
|
|
56
58
|
```ts
|
|
57
59
|
import { Effect, Layer } from "effect";
|
|
@@ -92,6 +94,53 @@ Provide `AdminSessions` once to `admin.handlers` and pass it with `admin.group`
|
|
|
92
94
|
|
|
93
95
|
Browser composition uses `mergeAdminRegistries` from `@shivaedev/admin/registry.ts` with the modules' browser-safe registries. A client module can also contribute its registry's `pages` directly to the application's navigation. A feature module adds pages to its own registry and handlers to its own registration; the foundation does not import feature pages.
|
|
94
96
|
|
|
97
|
+
### Keep admin code in admin paths
|
|
98
|
+
|
|
99
|
+
An `admin/` path segment means admin-only code. A wholly admin-only feature lives under `src/modules/admin/<name>`, with its shared declarations, `server/` and `client/` there. Admin tools for a member feature stay inside that feature: `admin/` for browser-safe page declarations, `server/admin/` for reads and handlers, and `client/admin/` for bindings and views. Each module reads only its own tables; compose another module's exposed operations for data it owns. Permissions enforce access regardless of the path.
|
|
100
|
+
|
|
101
|
+
The starter declares `StatisticsPage` with `adminPage` in [`src/modules/notes/admin/pages.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/admin/pages.ts). Its all-user read lives in [`src/modules/notes/server/admin/readStatistics.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/server/admin/readStatistics.ts):
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
import { Effect, Schema } from "effect";
|
|
105
|
+
import { SqlClient, SqlSchema } from "effect/sql";
|
|
106
|
+
import { NoteStatistics } from "#modules/notes/admin/pages.ts";
|
|
107
|
+
import { notesSqlFailure } from "#modules/notes/server/sqlFailure.ts";
|
|
108
|
+
|
|
109
|
+
export const readStatistics = Effect.fn("Notes.readStatistics")(function* () {
|
|
110
|
+
const sql = yield* SqlClient.SqlClient;
|
|
111
|
+
const read = SqlSchema.findOne({
|
|
112
|
+
execute: () => sql`select count(*)::int as notes, count(*) filter (where word_count is null)::int as pending,
|
|
113
|
+
coalesce(sum(word_count), 0)::int as words from notes`,
|
|
114
|
+
Request: Schema.Void,
|
|
115
|
+
Result: NoteStatistics,
|
|
116
|
+
});
|
|
117
|
+
return yield* read(undefined).pipe(Effect.catchTag("SqlError", (cause) => Effect.fail(notesSqlFailure(cause))));
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
[`src/modules/notes/server/admin/registration.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/server/admin/registration.ts) pairs that read with the page:
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
import { registerAdmin } from "@shivaedev/admin/server/registerAdmin.ts";
|
|
125
|
+
import { rpcBoundary } from "@shivaedev/errors/boundary.ts";
|
|
126
|
+
import { InternalServerError } from "@shivaedev/errors/taxonomy.ts";
|
|
127
|
+
import { Admin, StatisticsPage } from "#modules/notes/admin/pages.ts";
|
|
128
|
+
import { readStatistics } from "./readStatistics.ts";
|
|
129
|
+
|
|
130
|
+
const statistics = StatisticsPage.contract.application.toLayer({
|
|
131
|
+
"admin.notes.statistics": () =>
|
|
132
|
+
readStatistics().pipe(
|
|
133
|
+
rpcBoundary(StatisticsPage.contract.declaration.queries[0].error, { unexpected: (message) => new InternalServerError({ message }) }),
|
|
134
|
+
),
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
export const adminRegistration = registerAdmin(Admin, {
|
|
138
|
+
"note-statistics": statistics,
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The read stays in notes because notes owns the table. The [client registration](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/client/admin/registration.tsx) and view stay in `src/modules/notes/client/admin/`. Application composition may import these registrations from its member and admin module lists without moving their implementation out of the owning module.
|
|
143
|
+
|
|
95
144
|
### Built-in Jobs page
|
|
96
145
|
|
|
97
146
|
Share each queue's name and payload Schema with the browser declaration. The page exposes only the queues passed to `jobsPage`; a queue registered with the jobs runtime is not automatically available to operators.
|
package/dist/jobs/page.d.ts
CHANGED
|
@@ -147,25 +147,7 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
|
|
|
147
147
|
readonly id: string;
|
|
148
148
|
readonly queue: string;
|
|
149
149
|
}, import("@shivaedev/errors/taxonomy.ts").BadRequest | import("#jobs/schemas.ts").JobsPayloadInvalid | import("#jobs/schemas.ts").JobsQueueUnregistered | import("#jobs/schemas.ts").JobsUnavailable, import("@shivaedev/identity/identity.ts").SessionUser>;
|
|
150
|
-
}], readonly [], import("effect/rpc/Rpc").Rpc<"admin.jobs
|
|
151
|
-
id: Schema.String;
|
|
152
|
-
queue: Schema.String;
|
|
153
|
-
}>, Schema.OptionFromNullOr<Schema.Union<Schema.Struct<{
|
|
154
|
-
readonly attempt: Schema.Number;
|
|
155
|
-
readonly completedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
|
|
156
|
-
readonly createdOn: Schema.DateTimeUtcFromString;
|
|
157
|
-
readonly id: Schema.String;
|
|
158
|
-
readonly output: Schema.NullOr<Schema.Struct<{
|
|
159
|
-
readonly _tag: Schema.withDecodingDefaultKey<Schema.String, never>;
|
|
160
|
-
readonly message: Schema.decodeTo<Schema.String, Schema.String, never, never>;
|
|
161
|
-
}>>;
|
|
162
|
-
readonly retryCount: Schema.Number;
|
|
163
|
-
readonly retryLimit: Schema.Number;
|
|
164
|
-
readonly startedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
|
|
165
|
-
readonly state: Schema.Literals<readonly ["created", "retry", "active", "completed", "cancelled", "failed"]>;
|
|
166
|
-
readonly data: Schema.Unknown;
|
|
167
|
-
readonly queue: Schema.Literal<string>;
|
|
168
|
-
}>[]>>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.$changes", Schema.Struct<{
|
|
150
|
+
}], readonly [], import("effect/rpc/Rpc").Rpc<"admin.jobs.$changes", Schema.Struct<{
|
|
169
151
|
queries: Schema.$Array<Schema.Union<readonly (Schema.Struct<{
|
|
170
152
|
query: Schema.Literal<"counts">;
|
|
171
153
|
payload: Schema.Struct<{
|
|
@@ -220,20 +202,6 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
|
|
|
220
202
|
readonly failedCount: Schema.Number;
|
|
221
203
|
readonly queuedCount: Schema.Number;
|
|
222
204
|
readonly totalCount: Schema.Number;
|
|
223
|
-
}>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.health", Schema.Void, Schema.Struct<{
|
|
224
|
-
readonly activeTotal: Schema.Number;
|
|
225
|
-
readonly deadLetteredTotal: Schema.Number;
|
|
226
|
-
readonly failedTotal: Schema.Number;
|
|
227
|
-
readonly jobs: Schema.$Array<Schema.Struct<{
|
|
228
|
-
readonly activeCount: Schema.Number;
|
|
229
|
-
readonly deadLetteredCount: Schema.Number;
|
|
230
|
-
readonly failedCount: Schema.Number;
|
|
231
|
-
readonly name: Schema.String;
|
|
232
|
-
readonly queuedCount: Schema.Number;
|
|
233
|
-
readonly readyCount: Schema.Number;
|
|
234
|
-
}>>;
|
|
235
|
-
readonly queuedTotal: Schema.Number;
|
|
236
|
-
readonly readyTotal: Schema.Number;
|
|
237
205
|
}>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.failed", Schema.Struct<{
|
|
238
206
|
cursor: Schema.optionalKey<Schema.String>;
|
|
239
207
|
limit: Schema.Number;
|
|
@@ -284,6 +252,38 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
|
|
|
284
252
|
readonly sourceQueue: Schema.Literal<string>;
|
|
285
253
|
}>[]>>;
|
|
286
254
|
readonly next: Schema.OptionFromNullOr<Schema.String>;
|
|
255
|
+
}>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.job", Schema.Struct<{
|
|
256
|
+
id: Schema.String;
|
|
257
|
+
queue: Schema.String;
|
|
258
|
+
}>, Schema.OptionFromNullOr<Schema.Union<Schema.Struct<{
|
|
259
|
+
readonly attempt: Schema.Number;
|
|
260
|
+
readonly completedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
|
|
261
|
+
readonly createdOn: Schema.DateTimeUtcFromString;
|
|
262
|
+
readonly id: Schema.String;
|
|
263
|
+
readonly output: Schema.NullOr<Schema.Struct<{
|
|
264
|
+
readonly _tag: Schema.withDecodingDefaultKey<Schema.String, never>;
|
|
265
|
+
readonly message: Schema.decodeTo<Schema.String, Schema.String, never, never>;
|
|
266
|
+
}>>;
|
|
267
|
+
readonly retryCount: Schema.Number;
|
|
268
|
+
readonly retryLimit: Schema.Number;
|
|
269
|
+
readonly startedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
|
|
270
|
+
readonly state: Schema.Literals<readonly ["created", "retry", "active", "completed", "cancelled", "failed"]>;
|
|
271
|
+
readonly data: Schema.Unknown;
|
|
272
|
+
readonly queue: Schema.Literal<string>;
|
|
273
|
+
}>[]>>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.health", Schema.Void, Schema.Struct<{
|
|
274
|
+
readonly activeTotal: Schema.Number;
|
|
275
|
+
readonly deadLetteredTotal: Schema.Number;
|
|
276
|
+
readonly failedTotal: Schema.Number;
|
|
277
|
+
readonly jobs: Schema.$Array<Schema.Struct<{
|
|
278
|
+
readonly activeCount: Schema.Number;
|
|
279
|
+
readonly deadLetteredCount: Schema.Number;
|
|
280
|
+
readonly failedCount: Schema.Number;
|
|
281
|
+
readonly name: Schema.String;
|
|
282
|
+
readonly queuedCount: Schema.Number;
|
|
283
|
+
readonly readyCount: Schema.Number;
|
|
284
|
+
}>>;
|
|
285
|
+
readonly queuedTotal: Schema.Number;
|
|
286
|
+
readonly readyTotal: Schema.Number;
|
|
287
287
|
}>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never>, readonly [], undefined>;
|
|
288
288
|
} & {
|
|
289
289
|
queues: TQueues;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shivaedev/admin",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.2",
|
|
4
4
|
"description": "Explicit admin page contracts and a protected native Effect RPC registry",
|
|
5
5
|
"homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/admin#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -46,16 +46,16 @@
|
|
|
46
46
|
"@shivaedev/changes": "0.6.0",
|
|
47
47
|
"@shivaedev/contract": "0.30.0",
|
|
48
48
|
"@shivaedev/errors": "0.4.0",
|
|
49
|
-
"@shivaedev/identity": "0.
|
|
50
|
-
"@shivaedev/jobs": "0.28.
|
|
51
|
-
"@shivaedev/react": "0.
|
|
49
|
+
"@shivaedev/identity": "0.15.0",
|
|
50
|
+
"@shivaedev/jobs": "0.28.3",
|
|
51
|
+
"@shivaedev/react": "0.31.0"
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
54
|
"@effect/atom-react": "4.0.6",
|
|
55
|
-
"@shivaedev/quality": "0.
|
|
56
|
-
"@shivaedev/server": "0.
|
|
57
|
-
"@shivaedev/test-sql": "0.15.
|
|
58
|
-
"@shivaedev/test-story": "0.31.
|
|
55
|
+
"@shivaedev/quality": "0.53.0",
|
|
56
|
+
"@shivaedev/server": "0.16.0",
|
|
57
|
+
"@shivaedev/test-sql": "0.15.3",
|
|
58
|
+
"@shivaedev/test-story": "0.31.3",
|
|
59
59
|
"@types/node": "24.19.2",
|
|
60
60
|
"@types/react": "19.3.0",
|
|
61
61
|
"@types/react-dom": "19.3.0",
|