@molecule/api-resource-article 0.0.0-stage → 1.0.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.
- package/LICENSE +202 -0
- package/README.md +647 -2
- package/dist/authorizers/index.d.ts +11 -0
- package/dist/authorizers/index.d.ts.map +1 -0
- package/dist/authorizers/index.js +10 -0
- package/dist/browser-guard.d.ts +2 -0
- package/dist/browser-guard.d.ts.map +1 -0
- package/dist/browser-guard.js +18 -0
- package/dist/handlers/index.d.ts +61 -0
- package/dist/handlers/index.d.ts.map +1 -0
- package/dist/handlers/index.js +175 -0
- package/dist/handlers/shared.d.ts +64 -0
- package/dist/handlers/shared.d.ts.map +1 -0
- package/dist/handlers/shared.js +87 -0
- package/dist/index.d.ts +84 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +83 -0
- package/dist/requestHandlerMap.d.ts +21 -0
- package/dist/requestHandlerMap.d.ts.map +1 -0
- package/dist/requestHandlerMap.js +20 -0
- package/dist/routes.d.ts +56 -0
- package/dist/routes.d.ts.map +1 -0
- package/dist/routes.js +33 -0
- package/dist/service.d.ts +117 -0
- package/dist/service.d.ts.map +1 -0
- package/dist/service.js +343 -0
- package/dist/types.d.ts +122 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +6 -0
- package/dist/validation.d.ts +25 -0
- package/dist/validation.d.ts.map +1 -0
- package/dist/validation.js +26 -0
- package/package.json +78 -4
- package/src/__setup__/articles.sql +24 -0
package/README.md
CHANGED
|
@@ -1,3 +1,648 @@
|
|
|
1
|
-
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-10-15T09:18:33.058Z
|
|
7
|
+
-->
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
# @molecule/api-resource-article
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
Articles and blog posts for molecule.dev.
|
|
16
|
+
|
|
17
|
+
Articles with unique slugs, tags, favorites, a feed of the authors a user
|
|
18
|
+
follows, and lists filtered by tag, author and who favorited them — the
|
|
19
|
+
domain of a blog, a Medium-style platform (RealWorld "Conduit"), a news or
|
|
20
|
+
docs site. Favorites are `@molecule/api-resource-reaction` reactions and the
|
|
21
|
+
feed reads `@molecule/api-resource-follow`'s follows, so they are the same
|
|
22
|
+
favorites and follows the rest of the app sees.
|
|
23
|
+
|
|
24
|
+
## Quick Start
|
|
25
|
+
|
|
26
|
+
```typescript
|
|
27
|
+
import { routes, requestHandlerMap } from '@molecule/api-resource-article'
|
|
28
|
+
|
|
29
|
+
// Wire routes into your Express app via mlcl inject:
|
|
30
|
+
// POST /articles create (signed in)
|
|
31
|
+
// GET /articles ?tag= &author= &favoritedBy= &limit= &offset=
|
|
32
|
+
// GET /articles/feed authors the signed-in user follows
|
|
33
|
+
// GET /articles/tags tags in use, most-used first
|
|
34
|
+
// GET /articles/:slug
|
|
35
|
+
// PUT /articles/:slug author only; a new title gives a new slug
|
|
36
|
+
// DELETE /articles/:slug author only
|
|
37
|
+
// POST /articles/:slug/favorite idempotent
|
|
38
|
+
// DELETE /articles/:slug/favorite idempotent
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
// An API with its own response shape (a spec you must match) uses the
|
|
43
|
+
// service and writes its own envelope:
|
|
44
|
+
import { createArticle, listArticles } from '@molecule/api-resource-article'
|
|
45
|
+
|
|
46
|
+
router.post('/api/articles', authenticate, async (req, res) => {
|
|
47
|
+
const article = await createArticle(userId, req.body.article)
|
|
48
|
+
res.status(201).json({ article: { ...article, author: await profileOf(article.authorId) } })
|
|
49
|
+
})
|
|
50
|
+
|
|
51
|
+
const page = await listArticles({ tag: 'dragons', limit: 20, offset: 0, viewerId })
|
|
52
|
+
// page.data[0].favorited, page.data[0].favoritesCount, page.total
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Type
|
|
56
|
+
|
|
57
|
+
`resource`
|
|
58
|
+
|
|
59
|
+
## Installation
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install @molecule/api-resource-article @molecule/api-database @molecule/api-i18n @molecule/api-logger @molecule/api-resource @molecule/api-resource-follow @molecule/api-resource-reaction @molecule/api-slug zod
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## API
|
|
66
|
+
|
|
67
|
+
### Interfaces
|
|
68
|
+
|
|
69
|
+
#### `Article`
|
|
70
|
+
|
|
71
|
+
An article as the service returns it: tags decoded, favorites counted, and
|
|
72
|
+
whether the viewing user favorited it.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
interface Article {
|
|
76
|
+
/** Unique article identifier. */
|
|
77
|
+
id: string
|
|
78
|
+
/** URL slug, unique across articles. */
|
|
79
|
+
slug: string
|
|
80
|
+
/** Title. */
|
|
81
|
+
title: string
|
|
82
|
+
/** Short summary shown in lists. */
|
|
83
|
+
description: string
|
|
84
|
+
/** Full body. */
|
|
85
|
+
body: string
|
|
86
|
+
/** Tag names, in the order they were given. */
|
|
87
|
+
tagList: string[]
|
|
88
|
+
/** The user who wrote it. */
|
|
89
|
+
authorId: string
|
|
90
|
+
/** When it was created (ISO 8601). */
|
|
91
|
+
createdAt: string
|
|
92
|
+
/** When it was last updated (ISO 8601). */
|
|
93
|
+
updatedAt: string
|
|
94
|
+
/** How many users favorited it. */
|
|
95
|
+
favoritesCount: number
|
|
96
|
+
/** Whether the viewing user favorited it (`false` with no viewer). */
|
|
97
|
+
favorited: boolean
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
#### `ArticleRow`
|
|
102
|
+
|
|
103
|
+
An article row as stored. `tagList` is a JSON array of tag names.
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
interface ArticleRow {
|
|
107
|
+
/** Unique article identifier. */
|
|
108
|
+
id: string
|
|
109
|
+
/** URL slug, unique across articles. */
|
|
110
|
+
slug: string
|
|
111
|
+
/** Title. */
|
|
112
|
+
title: string
|
|
113
|
+
/** Short summary shown in lists. */
|
|
114
|
+
description: string
|
|
115
|
+
/** Full body (markdown or plain text — the app decides how to render it). */
|
|
116
|
+
body: string
|
|
117
|
+
/** Tag names, JSON-encoded. */
|
|
118
|
+
tagList: string
|
|
119
|
+
/** The user who wrote it. */
|
|
120
|
+
authorId: string
|
|
121
|
+
/** When it was created (ISO 8601, millisecond precision). */
|
|
122
|
+
createdAt: string
|
|
123
|
+
/** When it was last updated (ISO 8601). */
|
|
124
|
+
updatedAt: string
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
#### `CreateArticleInput`
|
|
129
|
+
|
|
130
|
+
Input for creating an article.
|
|
131
|
+
|
|
132
|
+
```typescript
|
|
133
|
+
interface CreateArticleInput {
|
|
134
|
+
/** Title (the slug is derived from it). */
|
|
135
|
+
title: string
|
|
136
|
+
/** Short summary. */
|
|
137
|
+
description?: string
|
|
138
|
+
/** Full body. */
|
|
139
|
+
body: string
|
|
140
|
+
/** Tag names. */
|
|
141
|
+
tagList?: string[]
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
#### `ListArticlesOptions`
|
|
146
|
+
|
|
147
|
+
Filters and paging for {@link listArticles}.
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
interface ListArticlesOptions {
|
|
151
|
+
/** Only articles with this tag. */
|
|
152
|
+
tag?: string
|
|
153
|
+
/** Only articles by this author id. */
|
|
154
|
+
authorId?: string
|
|
155
|
+
/** Only articles this user id favorited. */
|
|
156
|
+
favoritedBy?: string
|
|
157
|
+
/** Page size (default 20, at most 100). */
|
|
158
|
+
limit?: number
|
|
159
|
+
/** Rows to skip. */
|
|
160
|
+
offset?: number
|
|
161
|
+
/** The viewing user, for `favorited`. */
|
|
162
|
+
viewerId?: string
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
#### `PaginatedArticles`
|
|
167
|
+
|
|
168
|
+
A page of articles.
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
interface PaginatedArticles {
|
|
172
|
+
/** The articles on this page, newest first. */
|
|
173
|
+
data: Article[]
|
|
174
|
+
/** Articles matching the filters across all pages. */
|
|
175
|
+
total: number
|
|
176
|
+
/** Page size used. */
|
|
177
|
+
limit: number
|
|
178
|
+
/** Rows skipped. */
|
|
179
|
+
offset: number
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
#### `TagCount`
|
|
184
|
+
|
|
185
|
+
A tag and how many articles carry it.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
interface TagCount {
|
|
189
|
+
/** Tag name. */
|
|
190
|
+
tag: string
|
|
191
|
+
/** Articles with this tag. */
|
|
192
|
+
count: number
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
#### `UpdateArticleInput`
|
|
197
|
+
|
|
198
|
+
Input for updating an article. A changed title gives the article a new slug.
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
interface UpdateArticleInput {
|
|
202
|
+
/** New title. */
|
|
203
|
+
title?: string
|
|
204
|
+
/** New summary. */
|
|
205
|
+
description?: string
|
|
206
|
+
/** New body. */
|
|
207
|
+
body?: string
|
|
208
|
+
/** New tag names (replaces the old ones). */
|
|
209
|
+
tagList?: string[]
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Types
|
|
214
|
+
|
|
215
|
+
#### `AuthorChange`
|
|
216
|
+
|
|
217
|
+
The outcome of a change that only the author may make.
|
|
218
|
+
|
|
219
|
+
```typescript
|
|
220
|
+
type AuthorChange<T> =
|
|
221
|
+
{ status: 'ok'; article: T } | { status: 'not_found' } | { status: 'forbidden' }
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Functions
|
|
225
|
+
|
|
226
|
+
#### `create(req, res)`
|
|
227
|
+
|
|
228
|
+
`POST /articles` — create an article as the signed-in user.
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
function create(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
- `req` — Body: `{ title, body, description?, tagList? }`.
|
|
235
|
+
- `res` — 201 with the article.
|
|
236
|
+
|
|
237
|
+
#### `createArticle(authorId, input)`
|
|
238
|
+
|
|
239
|
+
Create an article with a unique slug derived from its title.
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
function createArticle(authorId: string, input: CreateArticleInput): Promise<Article>
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
- `authorId` — The writing user.
|
|
246
|
+
- `input` — Title, body, optional description and tags.
|
|
247
|
+
|
|
248
|
+
**Returns:** The created article.
|
|
249
|
+
|
|
250
|
+
#### `del(req, res)`
|
|
251
|
+
|
|
252
|
+
`DELETE /articles/:slug` — author only.
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
function del(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
- `req` — The request.
|
|
259
|
+
- `res` — 204, 403 or 404.
|
|
260
|
+
|
|
261
|
+
#### `deleteArticle(slug, userId)`
|
|
262
|
+
|
|
263
|
+
Delete an article and its tags and favorites. Only its author may.
|
|
264
|
+
|
|
265
|
+
```typescript
|
|
266
|
+
function deleteArticle(slug: string, userId: string): Promise<AuthorChange<true>>
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
- `slug` — The article slug.
|
|
270
|
+
- `userId` — The requesting user.
|
|
271
|
+
|
|
272
|
+
**Returns:** Whether it was deleted, or why not.
|
|
273
|
+
|
|
274
|
+
#### `feed(req, res)`
|
|
275
|
+
|
|
276
|
+
`GET /articles/feed` — articles by the authors the signed-in user follows.
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
function feed(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
- `req` — `?limit=`, `?offset=`.
|
|
283
|
+
- `res` — `{ data, total, limit, offset }`.
|
|
284
|
+
|
|
285
|
+
#### `findArticleRow(slug)`
|
|
286
|
+
|
|
287
|
+
The stored row for a slug.
|
|
288
|
+
|
|
289
|
+
```typescript
|
|
290
|
+
function findArticleRow(slug: string): Promise<ArticleRow | null>
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
- `slug` — The article slug.
|
|
294
|
+
|
|
295
|
+
**Returns:** The row, or null.
|
|
296
|
+
|
|
297
|
+
#### `getArticleBySlug(slug, viewerId)`
|
|
298
|
+
|
|
299
|
+
An article by slug.
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
function getArticleBySlug(slug: string, viewerId?: string): Promise<Article | null>
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
- `slug` — The article slug.
|
|
306
|
+
- `viewerId` — The viewing user, for `favorited`.
|
|
307
|
+
|
|
308
|
+
**Returns:** The article, or null.
|
|
309
|
+
|
|
310
|
+
#### `getFeed(userId, options)`
|
|
311
|
+
|
|
312
|
+
Articles by the users `userId` follows, newest first.
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
function getFeed(
|
|
316
|
+
userId: string,
|
|
317
|
+
options?: { limit?: number; offset?: number },
|
|
318
|
+
): Promise<PaginatedArticles>
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
- `userId` — The reader.
|
|
322
|
+
- `options` — Paging.
|
|
323
|
+
|
|
324
|
+
**Returns:** A page of articles and the total.
|
|
325
|
+
|
|
326
|
+
#### `hydrateArticles(rows, viewerId)`
|
|
327
|
+
|
|
328
|
+
Turn stored rows into {@link Article}s: decoded tags, favorite counts and the
|
|
329
|
+
viewer's own favorites, in two queries for the whole page.
|
|
330
|
+
|
|
331
|
+
```typescript
|
|
332
|
+
function hydrateArticles(rows: ArticleRow[], viewerId?: string): Promise<Article[]>
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
- `rows` — Article rows.
|
|
336
|
+
- `viewerId` — The viewing user, if any.
|
|
337
|
+
|
|
338
|
+
**Returns:** The articles, in the order given.
|
|
339
|
+
|
|
340
|
+
#### `list(req, res)`
|
|
341
|
+
|
|
342
|
+
`GET /articles` — newest first; `?tag=`, `?author=` (user id),
|
|
343
|
+
`?favoritedBy=` (user id), `?limit=`, `?offset=`.
|
|
344
|
+
|
|
345
|
+
```typescript
|
|
346
|
+
function list(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
- `req` — The request.
|
|
350
|
+
- `res` — `{ data, total, limit, offset }`.
|
|
351
|
+
|
|
352
|
+
#### `listArticles(options)`
|
|
353
|
+
|
|
354
|
+
Articles newest first, filtered by tag, author and who favorited them.
|
|
355
|
+
|
|
356
|
+
```typescript
|
|
357
|
+
function listArticles(options?: ListArticlesOptions): Promise<PaginatedArticles>
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
- `options` — Filters, paging and the viewer.
|
|
361
|
+
|
|
362
|
+
**Returns:** A page of articles and the total matching.
|
|
363
|
+
|
|
364
|
+
#### `popularTags(limit)`
|
|
365
|
+
|
|
366
|
+
Tags in use, most-used first.
|
|
367
|
+
|
|
368
|
+
```typescript
|
|
369
|
+
function popularTags(limit?: number): Promise<TagCount[]>
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
- `limit` — How many to return (default 20).
|
|
373
|
+
|
|
374
|
+
**Returns:** Tags with their article counts.
|
|
375
|
+
|
|
376
|
+
#### `read(req, res)`
|
|
377
|
+
|
|
378
|
+
`GET /articles/:slug`.
|
|
379
|
+
|
|
380
|
+
```typescript
|
|
381
|
+
function read(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
- `req` — The request.
|
|
385
|
+
- `res` — The article, or 404.
|
|
386
|
+
|
|
387
|
+
#### `setFavorite(slug, userId, favorite)`
|
|
388
|
+
|
|
389
|
+
Favorite or unfavorite an article for a user (idempotent both ways).
|
|
390
|
+
|
|
391
|
+
```typescript
|
|
392
|
+
function setFavorite(slug: string, userId: string, favorite: boolean): Promise<Article | null>
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
- `slug` — The article slug.
|
|
396
|
+
- `userId` — The user.
|
|
397
|
+
- `favorite` — True to favorite, false to remove the favorite.
|
|
398
|
+
|
|
399
|
+
**Returns:** The article after the change, or null when there is no such article.
|
|
400
|
+
|
|
401
|
+
#### `tags(req, res)`
|
|
402
|
+
|
|
403
|
+
`GET /articles/tags` — tags in use, most-used first (`?limit=`).
|
|
404
|
+
|
|
405
|
+
```typescript
|
|
406
|
+
function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
- `req` — The request.
|
|
410
|
+
- `res` — `[{ tag, count }]`.
|
|
411
|
+
|
|
412
|
+
#### `update(req, res)`
|
|
413
|
+
|
|
414
|
+
`PUT /articles/:slug` — author only; a new title gives a new slug.
|
|
415
|
+
|
|
416
|
+
```typescript
|
|
417
|
+
function update(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
- `req` — Body: any of `{ title, description, body, tagList }`.
|
|
421
|
+
- `res` — The updated article, 403 or 404.
|
|
422
|
+
|
|
423
|
+
#### `updateArticle(slug, userId, input)`
|
|
424
|
+
|
|
425
|
+
Update an article. Only its author may; a changed title gives it a new slug.
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
function updateArticle(
|
|
429
|
+
slug: string,
|
|
430
|
+
userId: string,
|
|
431
|
+
input: UpdateArticleInput,
|
|
432
|
+
): Promise<AuthorChange<Article>>
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
- `slug` — The article slug.
|
|
436
|
+
- `userId` — The requesting user.
|
|
437
|
+
- `input` — The fields to change.
|
|
438
|
+
|
|
439
|
+
**Returns:** The updated article, or why not.
|
|
440
|
+
|
|
441
|
+
### Constants
|
|
442
|
+
|
|
443
|
+
#### `ARTICLE_RESOURCE_TYPE`
|
|
444
|
+
|
|
445
|
+
The resource type favorites and comments on articles are stored under.
|
|
446
|
+
|
|
447
|
+
```typescript
|
|
448
|
+
const ARTICLE_RESOURCE_TYPE: 'article'
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
#### `createArticleSchema`
|
|
452
|
+
|
|
453
|
+
Schema for creating an article.
|
|
454
|
+
|
|
455
|
+
```typescript
|
|
456
|
+
const createArticleSchema: z.ZodObject<
|
|
457
|
+
{
|
|
458
|
+
title: z.ZodString
|
|
459
|
+
description: z.ZodOptional<z.ZodString>
|
|
460
|
+
body: z.ZodString
|
|
461
|
+
tagList: z.ZodOptional<z.ZodArray<z.ZodString>>
|
|
462
|
+
},
|
|
463
|
+
z.core.$strip
|
|
464
|
+
>
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
#### `favorite`
|
|
468
|
+
|
|
469
|
+
`POST /articles/:slug/favorite` — idempotent; returns the article.
|
|
470
|
+
|
|
471
|
+
```typescript
|
|
472
|
+
const favorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
#### `FAVORITE_REACTION`
|
|
476
|
+
|
|
477
|
+
The reaction type a favorite is stored as.
|
|
478
|
+
|
|
479
|
+
```typescript
|
|
480
|
+
const FAVORITE_REACTION: 'favorite'
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
#### `MAX_ARTICLES_PAGE`
|
|
484
|
+
|
|
485
|
+
Largest page a list returns.
|
|
486
|
+
|
|
487
|
+
```typescript
|
|
488
|
+
const MAX_ARTICLES_PAGE: 100
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
#### `requestHandlerMap`
|
|
492
|
+
|
|
493
|
+
Handler map for article routes.
|
|
494
|
+
|
|
495
|
+
```typescript
|
|
496
|
+
const requestHandlerMap: {
|
|
497
|
+
readonly create: typeof create
|
|
498
|
+
readonly list: typeof list
|
|
499
|
+
readonly feed: typeof feed
|
|
500
|
+
readonly tags: typeof tags
|
|
501
|
+
readonly read: typeof read
|
|
502
|
+
readonly update: typeof update
|
|
503
|
+
readonly del: typeof del
|
|
504
|
+
readonly favorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
505
|
+
readonly unfavorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
#### `RESERVED_ARTICLE_SLUGS`
|
|
510
|
+
|
|
511
|
+
Slugs the routes use for themselves (`/articles/feed`, `/articles/tags`): an
|
|
512
|
+
article titled "Feed" gets `feed-2`, or its page would be unreachable.
|
|
513
|
+
|
|
514
|
+
```typescript
|
|
515
|
+
const RESERVED_ARTICLE_SLUGS: ReadonlySet<string>
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
#### `routes`
|
|
519
|
+
|
|
520
|
+
Routes for articles, the feed, tags and favorites.
|
|
521
|
+
|
|
522
|
+
```typescript
|
|
523
|
+
const routes: readonly [
|
|
524
|
+
{
|
|
525
|
+
readonly method: 'post'
|
|
526
|
+
readonly path: '/articles'
|
|
527
|
+
readonly handler: 'create'
|
|
528
|
+
readonly middlewares: readonly ['authenticate']
|
|
529
|
+
},
|
|
530
|
+
{ readonly method: 'get'; readonly path: '/articles'; readonly handler: 'list' },
|
|
531
|
+
{
|
|
532
|
+
readonly method: 'get'
|
|
533
|
+
readonly path: '/articles/feed'
|
|
534
|
+
readonly handler: 'feed'
|
|
535
|
+
readonly middlewares: readonly ['authenticate']
|
|
536
|
+
},
|
|
537
|
+
{ readonly method: 'get'; readonly path: '/articles/tags'; readonly handler: 'tags' },
|
|
538
|
+
{ readonly method: 'get'; readonly path: '/articles/:slug'; readonly handler: 'read' },
|
|
539
|
+
{
|
|
540
|
+
readonly method: 'put'
|
|
541
|
+
readonly path: '/articles/:slug'
|
|
542
|
+
readonly handler: 'update'
|
|
543
|
+
readonly middlewares: readonly ['authenticate']
|
|
544
|
+
},
|
|
545
|
+
{
|
|
546
|
+
readonly method: 'delete'
|
|
547
|
+
readonly path: '/articles/:slug'
|
|
548
|
+
readonly handler: 'del'
|
|
549
|
+
readonly middlewares: readonly ['authenticate']
|
|
550
|
+
},
|
|
551
|
+
{
|
|
552
|
+
readonly method: 'post'
|
|
553
|
+
readonly path: '/articles/:slug/favorite'
|
|
554
|
+
readonly handler: 'favorite'
|
|
555
|
+
readonly middlewares: readonly ['authenticate']
|
|
556
|
+
},
|
|
557
|
+
{
|
|
558
|
+
readonly method: 'delete'
|
|
559
|
+
readonly path: '/articles/:slug/favorite'
|
|
560
|
+
readonly handler: 'unfavorite'
|
|
561
|
+
readonly middlewares: readonly ['authenticate']
|
|
562
|
+
},
|
|
563
|
+
]
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
#### `unfavorite`
|
|
567
|
+
|
|
568
|
+
`DELETE /articles/:slug/favorite` — idempotent; returns the article.
|
|
569
|
+
|
|
570
|
+
```typescript
|
|
571
|
+
const unfavorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
#### `updateArticleSchema`
|
|
575
|
+
|
|
576
|
+
Schema for updating an article (every field optional).
|
|
577
|
+
|
|
578
|
+
```typescript
|
|
579
|
+
const updateArticleSchema: z.ZodObject<
|
|
580
|
+
{
|
|
581
|
+
title: z.ZodOptional<z.ZodString>
|
|
582
|
+
description: z.ZodOptional<z.ZodString>
|
|
583
|
+
body: z.ZodOptional<z.ZodString>
|
|
584
|
+
tagList: z.ZodOptional<z.ZodArray<z.ZodString>>
|
|
585
|
+
},
|
|
586
|
+
z.core.$strip
|
|
587
|
+
>
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
## Injection Notes
|
|
591
|
+
|
|
592
|
+
### Requirements
|
|
593
|
+
|
|
594
|
+
Peer dependencies:
|
|
595
|
+
|
|
596
|
+
- `@molecule/api-database` ^1.0.1
|
|
597
|
+
- `@molecule/api-i18n` ^1.0.1
|
|
598
|
+
- `@molecule/api-logger` ^1.0.1
|
|
599
|
+
- `@molecule/api-resource` ^1.0.1
|
|
600
|
+
- `@molecule/api-resource-follow` ^1.0.5
|
|
601
|
+
- `@molecule/api-resource-reaction` ^1.0.3
|
|
602
|
+
- `@molecule/api-slug` ^1.0.0
|
|
603
|
+
- `zod` ^4.0.0
|
|
604
|
+
|
|
605
|
+
### Runtime Dependencies
|
|
606
|
+
|
|
607
|
+
- `@molecule/api-database`
|
|
608
|
+
- `@molecule/api-i18n`
|
|
609
|
+
- `@molecule/api-logger`
|
|
610
|
+
- `@molecule/api-resource`
|
|
611
|
+
- `@molecule/api-resource-follow`
|
|
612
|
+
- `@molecule/api-resource-reaction`
|
|
613
|
+
- `@molecule/api-slug`
|
|
614
|
+
- `zod`
|
|
615
|
+
|
|
616
|
+
- **Migration required.** `src/__setup__/articles.sql` creates `articles` and
|
|
617
|
+
`article_tags`; the reaction and follow packages bring `reactions` and
|
|
618
|
+
`follows`. Scaffolded apps apply all of them on boot.
|
|
619
|
+
- **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
|
|
620
|
+
at most 100 per page. `createdAt` is written with milliseconds, so two
|
|
621
|
+
articles from the same second still come back in order on SQLite.
|
|
622
|
+
- **Slugs are unique and stable.** The first "Hello World" is `hello-world`,
|
|
623
|
+
the next `hello-world-2`; `feed` and `tags` are never used (they are routes).
|
|
624
|
+
Changing the title changes the slug — link with the slug the response returns.
|
|
625
|
+
- **The author is the session user**, always: create ignores any client
|
|
626
|
+
author, and update/delete answer 403 to anyone else.
|
|
627
|
+
- **Reads are public**; `favorited` is `false` without a signed-in viewer.
|
|
628
|
+
- Article bodies are stored as given. Render markdown with
|
|
629
|
+
`@molecule/app-markdown` + a provider (sanitized HTML) on the client.
|
|
630
|
+
- Comments on articles: `@molecule/api-resource-comment` with resource type
|
|
631
|
+
`'article'` and the article id.
|
|
632
|
+
|
|
633
|
+
## E2E Tests
|
|
634
|
+
|
|
635
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
636
|
+
each item to this app's actual screens/flows, and check every box off one
|
|
637
|
+
by one. A box you can't check is an integration bug to fix — not a skip:
|
|
638
|
+
|
|
639
|
+
- [ ] Publishing an article opens its page at the slug the API returned,
|
|
640
|
+
and it shows first in the global list.
|
|
641
|
+
- [ ] Two articles with the same title get different slugs and both open.
|
|
642
|
+
- [ ] Filtering by a tag shows only articles with that tag.
|
|
643
|
+
- [ ] Favoriting increments the count, survives a reload, and unfavoriting
|
|
644
|
+
brings it back; a signed-out visitor sees the count but no "favorited".
|
|
645
|
+
- [ ] The feed shows only articles by followed authors, and an empty feed
|
|
646
|
+
shows a readable empty state.
|
|
647
|
+
- [ ] Only the author sees edit/delete; another user's direct attempt is refused.
|
|
648
|
+
- [ ] Deleting removes the article from every list after reload.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Article authorizers.
|
|
3
|
+
*
|
|
4
|
+
* Authorship is enforced in the service: only an article's author can update
|
|
5
|
+
* or delete it (`updateArticle`, `deleteArticle` return `forbidden`). No
|
|
6
|
+
* route-level authorizers are needed.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export {};
|
|
11
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authorizers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAA"}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Article authorizers.
|
|
3
|
+
*
|
|
4
|
+
* Authorship is enforced in the service: only an article's author can update
|
|
5
|
+
* or delete it (`updateArticle`, `deleteArticle` return `forbidden`). No
|
|
6
|
+
* route-level authorizers are needed.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser guard — `@molecule/api-resource-article` is SERVER-ONLY.
|
|
3
|
+
*
|
|
4
|
+
* Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
|
|
5
|
+
* Evaluating a server package in a browser bundle is always an import-graph mistake
|
|
6
|
+
* (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
|
|
7
|
+
* ("Buffer is not defined") far from the culprit. Throwing here names the package and
|
|
8
|
+
* the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
|
|
9
|
+
* unaffected: the throw requires browser globals AND the absence of a node runtime.
|
|
10
|
+
*/
|
|
11
|
+
const g = globalThis;
|
|
12
|
+
if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
|
|
13
|
+
throw new Error('@molecule/api-resource-article is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
|
|
14
|
+
'from server code (a server route/function or your API), or dynamic-import it inside ' +
|
|
15
|
+
'the server handler — never from components or shared client modules, and never ' +
|
|
16
|
+
'polyfill Buffer/process to silence this.');
|
|
17
|
+
}
|
|
18
|
+
export {};
|