@molecule/api-resource-article 1.0.1 → 1.0.3
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/README.md +184 -176
- package/dist/index.d.ts +9 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -1
- package/dist/service.d.ts.map +1 -1
- package/dist/service.js +25 -6
- package/package.json +3 -3
- package/src/__setup__/articles.sql +4 -0
- package/src/__setup__/articles_position.sql +30 -0
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-10-
|
|
6
|
+
Generated: 2026-10-16T01:58:33.609Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/api-resource-article
|
|
@@ -66,13 +66,12 @@ npm install @molecule/api-resource-article @molecule/api-database @molecule/api-
|
|
|
66
66
|
|
|
67
67
|
### Interfaces
|
|
68
68
|
|
|
69
|
-
#### `
|
|
69
|
+
#### `ArticleRow`
|
|
70
70
|
|
|
71
|
-
An article as
|
|
72
|
-
whether the viewing user favorited it.
|
|
71
|
+
An article row as stored. `tagList` is a JSON array of tag names.
|
|
73
72
|
|
|
74
73
|
```typescript
|
|
75
|
-
interface
|
|
74
|
+
interface ArticleRow {
|
|
76
75
|
/** Unique article identifier. */
|
|
77
76
|
id: string
|
|
78
77
|
/** URL slug, unique across articles. */
|
|
@@ -81,29 +80,26 @@ interface Article {
|
|
|
81
80
|
title: string
|
|
82
81
|
/** Short summary shown in lists. */
|
|
83
82
|
description: string
|
|
84
|
-
/** Full body. */
|
|
83
|
+
/** Full body (markdown or plain text — the app decides how to render it). */
|
|
85
84
|
body: string
|
|
86
|
-
/** Tag names,
|
|
87
|
-
tagList: string
|
|
85
|
+
/** Tag names, JSON-encoded. */
|
|
86
|
+
tagList: string
|
|
88
87
|
/** The user who wrote it. */
|
|
89
88
|
authorId: string
|
|
90
|
-
/** When it was created (ISO 8601). */
|
|
89
|
+
/** When it was created (ISO 8601, millisecond precision). */
|
|
91
90
|
createdAt: string
|
|
92
91
|
/** When it was last updated (ISO 8601). */
|
|
93
92
|
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
93
|
}
|
|
99
94
|
```
|
|
100
95
|
|
|
101
|
-
#### `
|
|
96
|
+
#### `Article`
|
|
102
97
|
|
|
103
|
-
An article
|
|
98
|
+
An article as the service returns it: tags decoded, favorites counted, and
|
|
99
|
+
whether the viewing user favorited it.
|
|
104
100
|
|
|
105
101
|
```typescript
|
|
106
|
-
interface
|
|
102
|
+
interface Article {
|
|
107
103
|
/** Unique article identifier. */
|
|
108
104
|
id: string
|
|
109
105
|
/** URL slug, unique across articles. */
|
|
@@ -112,16 +108,20 @@ interface ArticleRow {
|
|
|
112
108
|
title: string
|
|
113
109
|
/** Short summary shown in lists. */
|
|
114
110
|
description: string
|
|
115
|
-
/** Full body
|
|
111
|
+
/** Full body. */
|
|
116
112
|
body: string
|
|
117
|
-
/** Tag names,
|
|
118
|
-
tagList: string
|
|
113
|
+
/** Tag names, in the order they were given. */
|
|
114
|
+
tagList: string[]
|
|
119
115
|
/** The user who wrote it. */
|
|
120
116
|
authorId: string
|
|
121
|
-
/** When it was created (ISO 8601
|
|
117
|
+
/** When it was created (ISO 8601). */
|
|
122
118
|
createdAt: string
|
|
123
119
|
/** When it was last updated (ISO 8601). */
|
|
124
120
|
updatedAt: string
|
|
121
|
+
/** How many users favorited it. */
|
|
122
|
+
favoritesCount: number
|
|
123
|
+
/** Whether the viewing user favorited it (`false` with no viewer). */
|
|
124
|
+
favorited: boolean
|
|
125
125
|
}
|
|
126
126
|
```
|
|
127
127
|
|
|
@@ -142,6 +142,23 @@ interface CreateArticleInput {
|
|
|
142
142
|
}
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
+
#### `UpdateArticleInput`
|
|
146
|
+
|
|
147
|
+
Input for updating an article. A changed title gives the article a new slug.
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
interface UpdateArticleInput {
|
|
151
|
+
/** New title. */
|
|
152
|
+
title?: string
|
|
153
|
+
/** New summary. */
|
|
154
|
+
description?: string
|
|
155
|
+
/** New body. */
|
|
156
|
+
body?: string
|
|
157
|
+
/** New tag names (replaces the old ones). */
|
|
158
|
+
tagList?: string[]
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
145
162
|
#### `ListArticlesOptions`
|
|
146
163
|
|
|
147
164
|
Filters and paging for {@link listArticles}.
|
|
@@ -193,23 +210,6 @@ interface TagCount {
|
|
|
193
210
|
}
|
|
194
211
|
```
|
|
195
212
|
|
|
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
213
|
### Types
|
|
214
214
|
|
|
215
215
|
#### `AuthorChange`
|
|
@@ -234,42 +234,17 @@ function create(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
|
234
234
|
- `req` — Body: `{ title, body, description?, tagList? }`.
|
|
235
235
|
- `res` — 201 with the article.
|
|
236
236
|
|
|
237
|
-
#### `
|
|
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)`
|
|
237
|
+
#### `list(req, res)`
|
|
251
238
|
|
|
252
|
-
`
|
|
239
|
+
`GET /articles` — newest first; `?tag=`, `?author=` (user id),
|
|
240
|
+
`?favoritedBy=` (user id), `?limit=`, `?offset=`.
|
|
253
241
|
|
|
254
242
|
```typescript
|
|
255
|
-
function
|
|
243
|
+
function list(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
256
244
|
```
|
|
257
245
|
|
|
258
246
|
- `req` — The request.
|
|
259
|
-
- `res` —
|
|
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.
|
|
247
|
+
- `res` — `{ data, total, limit, offset }`.
|
|
273
248
|
|
|
274
249
|
#### `feed(req, res)`
|
|
275
250
|
|
|
@@ -282,46 +257,49 @@ function feed(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
|
282
257
|
- `req` — `?limit=`, `?offset=`.
|
|
283
258
|
- `res` — `{ data, total, limit, offset }`.
|
|
284
259
|
|
|
285
|
-
#### `
|
|
260
|
+
#### `tags(req, res)`
|
|
286
261
|
|
|
287
|
-
|
|
262
|
+
`GET /articles/tags` — tags in use, most-used first (`?limit=`).
|
|
288
263
|
|
|
289
264
|
```typescript
|
|
290
|
-
function
|
|
265
|
+
function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
291
266
|
```
|
|
292
267
|
|
|
293
|
-
- `
|
|
294
|
-
|
|
295
|
-
**Returns:** The row, or null.
|
|
268
|
+
- `req` — The request.
|
|
269
|
+
- `res` — `[{ tag, count }]`.
|
|
296
270
|
|
|
297
|
-
#### `
|
|
271
|
+
#### `read(req, res)`
|
|
298
272
|
|
|
299
|
-
|
|
273
|
+
`GET /articles/:slug`.
|
|
300
274
|
|
|
301
275
|
```typescript
|
|
302
|
-
function
|
|
276
|
+
function read(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
303
277
|
```
|
|
304
278
|
|
|
305
|
-
- `
|
|
306
|
-
- `
|
|
307
|
-
|
|
308
|
-
**Returns:** The article, or null.
|
|
279
|
+
- `req` — The request.
|
|
280
|
+
- `res` — The article, or 404.
|
|
309
281
|
|
|
310
|
-
#### `
|
|
282
|
+
#### `update(req, res)`
|
|
311
283
|
|
|
312
|
-
|
|
284
|
+
`PUT /articles/:slug` — author only; a new title gives a new slug.
|
|
313
285
|
|
|
314
286
|
```typescript
|
|
315
|
-
function
|
|
316
|
-
userId: string,
|
|
317
|
-
options?: { limit?: number; offset?: number },
|
|
318
|
-
): Promise<PaginatedArticles>
|
|
287
|
+
function update(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
319
288
|
```
|
|
320
289
|
|
|
321
|
-
- `
|
|
322
|
-
- `
|
|
290
|
+
- `req` — Body: any of `{ title, description, body, tagList }`.
|
|
291
|
+
- `res` — The updated article, 403 or 404.
|
|
323
292
|
|
|
324
|
-
|
|
293
|
+
#### `del(req, res)`
|
|
294
|
+
|
|
295
|
+
`DELETE /articles/:slug` — author only.
|
|
296
|
+
|
|
297
|
+
```typescript
|
|
298
|
+
function del(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
- `req` — The request.
|
|
302
|
+
- `res` — 204, 403 or 404.
|
|
325
303
|
|
|
326
304
|
#### `hydrateArticles(rows, viewerId)`
|
|
327
305
|
|
|
@@ -337,88 +315,71 @@ function hydrateArticles(rows: ArticleRow[], viewerId?: string): Promise<Article
|
|
|
337
315
|
|
|
338
316
|
**Returns:** The articles, in the order given.
|
|
339
317
|
|
|
340
|
-
#### `
|
|
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)`
|
|
318
|
+
#### `createArticle(authorId, input)`
|
|
353
319
|
|
|
354
|
-
|
|
320
|
+
Create an article with a unique slug derived from its title.
|
|
355
321
|
|
|
356
322
|
```typescript
|
|
357
|
-
function
|
|
323
|
+
function createArticle(authorId: string, input: CreateArticleInput): Promise<Article>
|
|
358
324
|
```
|
|
359
325
|
|
|
360
|
-
- `
|
|
326
|
+
- `authorId` — The writing user.
|
|
327
|
+
- `input` — Title, body, optional description and tags.
|
|
361
328
|
|
|
362
|
-
**Returns:**
|
|
329
|
+
**Returns:** The created article.
|
|
363
330
|
|
|
364
|
-
#### `
|
|
331
|
+
#### `findArticleRow(slug)`
|
|
365
332
|
|
|
366
|
-
|
|
333
|
+
The stored row for a slug.
|
|
367
334
|
|
|
368
335
|
```typescript
|
|
369
|
-
function
|
|
336
|
+
function findArticleRow(slug: string): Promise<ArticleRow | null>
|
|
370
337
|
```
|
|
371
338
|
|
|
372
|
-
- `
|
|
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
|
-
```
|
|
339
|
+
- `slug` — The article slug.
|
|
383
340
|
|
|
384
|
-
|
|
385
|
-
- `res` — The article, or 404.
|
|
341
|
+
**Returns:** The row, or null.
|
|
386
342
|
|
|
387
|
-
#### `
|
|
343
|
+
#### `getArticleBySlug(slug, viewerId)`
|
|
388
344
|
|
|
389
|
-
|
|
345
|
+
An article by slug.
|
|
390
346
|
|
|
391
347
|
```typescript
|
|
392
|
-
function
|
|
348
|
+
function getArticleBySlug(slug: string, viewerId?: string): Promise<Article | null>
|
|
393
349
|
```
|
|
394
350
|
|
|
395
351
|
- `slug` — The article slug.
|
|
396
|
-
- `
|
|
397
|
-
- `favorite` — True to favorite, false to remove the favorite.
|
|
352
|
+
- `viewerId` — The viewing user, for `favorited`.
|
|
398
353
|
|
|
399
|
-
**Returns:** The article
|
|
354
|
+
**Returns:** The article, or null.
|
|
400
355
|
|
|
401
|
-
#### `
|
|
356
|
+
#### `listArticles(options)`
|
|
402
357
|
|
|
403
|
-
|
|
358
|
+
Articles newest first, filtered by tag, author and who favorited them.
|
|
404
359
|
|
|
405
360
|
```typescript
|
|
406
|
-
function
|
|
361
|
+
function listArticles(options?: ListArticlesOptions): Promise<PaginatedArticles>
|
|
407
362
|
```
|
|
408
363
|
|
|
409
|
-
- `
|
|
410
|
-
- `res` — `[{ tag, count }]`.
|
|
364
|
+
- `options` — Filters, paging and the viewer.
|
|
411
365
|
|
|
412
|
-
|
|
366
|
+
**Returns:** A page of articles and the total matching.
|
|
413
367
|
|
|
414
|
-
`
|
|
368
|
+
#### `getFeed(userId, options)`
|
|
369
|
+
|
|
370
|
+
Articles by the users `userId` follows, newest first.
|
|
415
371
|
|
|
416
372
|
```typescript
|
|
417
|
-
function
|
|
373
|
+
function getFeed(
|
|
374
|
+
userId: string,
|
|
375
|
+
options?: { limit?: number; offset?: number },
|
|
376
|
+
): Promise<PaginatedArticles>
|
|
418
377
|
```
|
|
419
378
|
|
|
420
|
-
- `
|
|
421
|
-
- `
|
|
379
|
+
- `userId` — The reader.
|
|
380
|
+
- `options` — Paging.
|
|
381
|
+
|
|
382
|
+
**Returns:** A page of articles and the total.
|
|
422
383
|
|
|
423
384
|
#### `updateArticle(slug, userId, input)`
|
|
424
385
|
|
|
@@ -438,54 +399,61 @@ function updateArticle(
|
|
|
438
399
|
|
|
439
400
|
**Returns:** The updated article, or why not.
|
|
440
401
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
#### `ARTICLE_RESOURCE_TYPE`
|
|
402
|
+
#### `deleteArticle(slug, userId)`
|
|
444
403
|
|
|
445
|
-
|
|
404
|
+
Delete an article and its tags and favorites. Only its author may.
|
|
446
405
|
|
|
447
406
|
```typescript
|
|
448
|
-
|
|
407
|
+
function deleteArticle(slug: string, userId: string): Promise<AuthorChange<true>>
|
|
449
408
|
```
|
|
450
409
|
|
|
451
|
-
|
|
410
|
+
- `slug` — The article slug.
|
|
411
|
+
- `userId` — The requesting user.
|
|
452
412
|
|
|
453
|
-
|
|
413
|
+
**Returns:** Whether it was deleted, or why not.
|
|
414
|
+
|
|
415
|
+
#### `setFavorite(slug, userId, favorite)`
|
|
416
|
+
|
|
417
|
+
Favorite or unfavorite an article for a user (idempotent both ways).
|
|
454
418
|
|
|
455
419
|
```typescript
|
|
456
|
-
|
|
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
|
-
>
|
|
420
|
+
function setFavorite(slug: string, userId: string, favorite: boolean): Promise<Article | null>
|
|
465
421
|
```
|
|
466
422
|
|
|
467
|
-
|
|
423
|
+
- `slug` — The article slug.
|
|
424
|
+
- `userId` — The user.
|
|
425
|
+
- `favorite` — True to favorite, false to remove the favorite.
|
|
468
426
|
|
|
469
|
-
|
|
427
|
+
**Returns:** The article after the change, or null when there is no such article.
|
|
428
|
+
|
|
429
|
+
#### `popularTags(limit)`
|
|
430
|
+
|
|
431
|
+
Tags in use, most-used first.
|
|
470
432
|
|
|
471
433
|
```typescript
|
|
472
|
-
|
|
434
|
+
function popularTags(limit?: number): Promise<TagCount[]>
|
|
473
435
|
```
|
|
474
436
|
|
|
475
|
-
|
|
437
|
+
- `limit` — How many to return (default 20).
|
|
476
438
|
|
|
477
|
-
|
|
439
|
+
**Returns:** Tags with their article counts.
|
|
440
|
+
|
|
441
|
+
### Constants
|
|
442
|
+
|
|
443
|
+
#### `favorite`
|
|
444
|
+
|
|
445
|
+
`POST /articles/:slug/favorite` — idempotent; returns the article.
|
|
478
446
|
|
|
479
447
|
```typescript
|
|
480
|
-
const
|
|
448
|
+
const favorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
481
449
|
```
|
|
482
450
|
|
|
483
|
-
#### `
|
|
451
|
+
#### `unfavorite`
|
|
484
452
|
|
|
485
|
-
|
|
453
|
+
`DELETE /articles/:slug/favorite` — idempotent; returns the article.
|
|
486
454
|
|
|
487
455
|
```typescript
|
|
488
|
-
const
|
|
456
|
+
const unfavorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
|
|
489
457
|
```
|
|
490
458
|
|
|
491
459
|
#### `requestHandlerMap`
|
|
@@ -506,15 +474,6 @@ const requestHandlerMap: {
|
|
|
506
474
|
}
|
|
507
475
|
```
|
|
508
476
|
|
|
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
477
|
#### `routes`
|
|
519
478
|
|
|
520
479
|
Routes for articles, the feed, tags and favorites.
|
|
@@ -563,12 +522,53 @@ const routes: readonly [
|
|
|
563
522
|
]
|
|
564
523
|
```
|
|
565
524
|
|
|
566
|
-
#### `
|
|
525
|
+
#### `ARTICLE_RESOURCE_TYPE`
|
|
567
526
|
|
|
568
|
-
|
|
527
|
+
The resource type favorites and comments on articles are stored under.
|
|
569
528
|
|
|
570
529
|
```typescript
|
|
571
|
-
const
|
|
530
|
+
const ARTICLE_RESOURCE_TYPE: 'article'
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
#### `FAVORITE_REACTION`
|
|
534
|
+
|
|
535
|
+
The reaction type a favorite is stored as.
|
|
536
|
+
|
|
537
|
+
```typescript
|
|
538
|
+
const FAVORITE_REACTION: 'favorite'
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
#### `RESERVED_ARTICLE_SLUGS`
|
|
542
|
+
|
|
543
|
+
Slugs the routes use for themselves (`/articles/feed`, `/articles/tags`): an
|
|
544
|
+
article titled "Feed" gets `feed-2`, or its page would be unreachable.
|
|
545
|
+
|
|
546
|
+
```typescript
|
|
547
|
+
const RESERVED_ARTICLE_SLUGS: ReadonlySet<string>
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
#### `MAX_ARTICLES_PAGE`
|
|
551
|
+
|
|
552
|
+
Largest page a list returns.
|
|
553
|
+
|
|
554
|
+
```typescript
|
|
555
|
+
const MAX_ARTICLES_PAGE: 100
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
#### `createArticleSchema`
|
|
559
|
+
|
|
560
|
+
Schema for creating an article.
|
|
561
|
+
|
|
562
|
+
```typescript
|
|
563
|
+
const createArticleSchema: z.ZodObject<
|
|
564
|
+
{
|
|
565
|
+
title: z.ZodString
|
|
566
|
+
description: z.ZodOptional<z.ZodString>
|
|
567
|
+
body: z.ZodString
|
|
568
|
+
tagList: z.ZodOptional<z.ZodArray<z.ZodString>>
|
|
569
|
+
},
|
|
570
|
+
z.core.$strip
|
|
571
|
+
>
|
|
572
572
|
```
|
|
573
573
|
|
|
574
574
|
#### `updateArticleSchema`
|
|
@@ -616,6 +616,12 @@ Peer dependencies:
|
|
|
616
616
|
- **Migration required.** `src/__setup__/articles.sql` creates `articles` and
|
|
617
617
|
`article_tags`; the reaction and follow packages bring `reactions` and
|
|
618
618
|
`follows`. Scaffolded apps apply all of them on boot.
|
|
619
|
+
`src/__setup__/articles_position.sql` adds `article_tags.position` to a
|
|
620
|
+
database whose table predates the column.
|
|
621
|
+
- **`article_tags` keeps the order the tags were given in**, in its `position`
|
|
622
|
+
column (0-based). An app that reads the join table itself must order by
|
|
623
|
+
`position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
|
|
624
|
+
the wrong tag otherwise. `Article.tagList` is already in that order.
|
|
619
625
|
- **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
|
|
620
626
|
at most 100 per page. `createdAt` is written with milliseconds, so two
|
|
621
627
|
articles from the same second still come back in order on SQLite.
|
|
@@ -628,7 +634,9 @@ Peer dependencies:
|
|
|
628
634
|
- Article bodies are stored as given. Render markdown with
|
|
629
635
|
`@molecule/app-markdown` + a provider (sanitized HTML) on the client.
|
|
630
636
|
- Comments on articles: `@molecule/api-resource-comment` with resource type
|
|
631
|
-
`'article'` and the article id.
|
|
637
|
+
`'article'` and the article id. An API whose comment ids are integers
|
|
638
|
+
(RealWorld's) creates them with its `createNumberedComment` and finds them with
|
|
639
|
+
`getCommentByNumber`.
|
|
632
640
|
|
|
633
641
|
## E2E Tests
|
|
634
642
|
|
package/dist/index.d.ts
CHANGED
|
@@ -44,6 +44,12 @@
|
|
|
44
44
|
* - **Migration required.** `src/__setup__/articles.sql` creates `articles` and
|
|
45
45
|
* `article_tags`; the reaction and follow packages bring `reactions` and
|
|
46
46
|
* `follows`. Scaffolded apps apply all of them on boot.
|
|
47
|
+
* `src/__setup__/articles_position.sql` adds `article_tags.position` to a
|
|
48
|
+
* database whose table predates the column.
|
|
49
|
+
* - **`article_tags` keeps the order the tags were given in**, in its `position`
|
|
50
|
+
* column (0-based). An app that reads the join table itself must order by
|
|
51
|
+
* `position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
|
|
52
|
+
* the wrong tag otherwise. `Article.tagList` is already in that order.
|
|
47
53
|
* - **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
|
|
48
54
|
* at most 100 per page. `createdAt` is written with milliseconds, so two
|
|
49
55
|
* articles from the same second still come back in order on SQLite.
|
|
@@ -56,7 +62,9 @@
|
|
|
56
62
|
* - Article bodies are stored as given. Render markdown with
|
|
57
63
|
* `@molecule/app-markdown` + a provider (sanitized HTML) on the client.
|
|
58
64
|
* - Comments on articles: `@molecule/api-resource-comment` with resource type
|
|
59
|
-
* `'article'` and the article id.
|
|
65
|
+
* `'article'` and the article id. An API whose comment ids are integers
|
|
66
|
+
* (RealWorld's) creates them with its `createNumberedComment` and finds them with
|
|
67
|
+
* `getCommentByNumber`.
|
|
60
68
|
*
|
|
61
69
|
* @e2e
|
|
62
70
|
* Integration checklist — drive the real UI (live preview, no mocks), adapt
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -44,6 +44,12 @@
|
|
|
44
44
|
* - **Migration required.** `src/__setup__/articles.sql` creates `articles` and
|
|
45
45
|
* `article_tags`; the reaction and follow packages bring `reactions` and
|
|
46
46
|
* `follows`. Scaffolded apps apply all of them on boot.
|
|
47
|
+
* `src/__setup__/articles_position.sql` adds `article_tags.position` to a
|
|
48
|
+
* database whose table predates the column.
|
|
49
|
+
* - **`article_tags` keeps the order the tags were given in**, in its `position`
|
|
50
|
+
* column (0-based). An app that reads the join table itself must order by
|
|
51
|
+
* `position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
|
|
52
|
+
* the wrong tag otherwise. `Article.tagList` is already in that order.
|
|
47
53
|
* - **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
|
|
48
54
|
* at most 100 per page. `createdAt` is written with milliseconds, so two
|
|
49
55
|
* articles from the same second still come back in order on SQLite.
|
|
@@ -56,7 +62,9 @@
|
|
|
56
62
|
* - Article bodies are stored as given. Render markdown with
|
|
57
63
|
* `@molecule/app-markdown` + a provider (sanitized HTML) on the client.
|
|
58
64
|
* - Comments on articles: `@molecule/api-resource-comment` with resource type
|
|
59
|
-
* `'article'` and the article id.
|
|
65
|
+
* `'article'` and the article id. An API whose comment ids are integers
|
|
66
|
+
* (RealWorld's) creates them with its `createNumberedComment` and finds them with
|
|
67
|
+
* `getCommentByNumber`.
|
|
60
68
|
*
|
|
61
69
|
* @e2e
|
|
62
70
|
* Integration checklist — drive the real UI (live preview, no mocks), adapt
|
package/dist/service.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;
|
|
1
|
+
{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAOnB,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAE9C,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAE3C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAA6B,CAAA;AA6BpF,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAyBpC;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA6B/F;AAsBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAsBjG;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAE7E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAK/F;AAkCD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoBhG;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC,iBAAiB,CAAC,CAsB5B;AAED,6DAA6D;AAC7D,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAA;AAElF;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAkBhC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAW7F;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAOzB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAYjE"}
|
package/dist/service.js
CHANGED
|
@@ -106,10 +106,23 @@ export async function hydrateArticles(rows, viewerId) {
|
|
|
106
106
|
favorited: mine.has(row.id),
|
|
107
107
|
}));
|
|
108
108
|
}
|
|
109
|
+
/**
|
|
110
|
+
* The order a reader of `article_tags` sees: the order the article gave its tags
|
|
111
|
+
* in, then the tag name to break the tie a row written outside this package (no
|
|
112
|
+
* `position`) would otherwise leave to the database.
|
|
113
|
+
*/
|
|
114
|
+
const TAGS_IN_ARTICLE_ORDER = [
|
|
115
|
+
{ field: 'position', direction: 'asc' },
|
|
116
|
+
{ field: 'tag', direction: 'asc' },
|
|
117
|
+
];
|
|
109
118
|
const writeTags = async (articleId, tags) => {
|
|
110
119
|
await deleteMany(ARTICLE_TAGS, [{ field: 'articleId', operator: '=', value: articleId }]);
|
|
111
|
-
|
|
112
|
-
|
|
120
|
+
// `position` is the array index so the join table keeps the submitted order —
|
|
121
|
+
// a reader of it (the tag filter below, an app's own query) must not depend on
|
|
122
|
+
// the row order the database happens to return.
|
|
123
|
+
for (const [position, tag] of tags.entries()) {
|
|
124
|
+
await dbCreate(ARTICLE_TAGS, { articleId, tag, position });
|
|
125
|
+
}
|
|
113
126
|
};
|
|
114
127
|
/**
|
|
115
128
|
* Create an article with a unique slug derived from its title.
|
|
@@ -121,9 +134,10 @@ const writeTags = async (articleId, tags) => {
|
|
|
121
134
|
export async function createArticle(authorId, input) {
|
|
122
135
|
const slug = await articleSlug(input.title);
|
|
123
136
|
const tags = cleanTags(input.tagList);
|
|
124
|
-
// Written here rather than
|
|
125
|
-
//
|
|
126
|
-
// first"
|
|
137
|
+
// Written here rather than left to the column default: the default is
|
|
138
|
+
// millisecond-precision, so two articles created inside the same millisecond
|
|
139
|
+
// would still tie and "newest first" would come back in either order. This one
|
|
140
|
+
// is strictly increasing per process (see nextCreatedAt).
|
|
127
141
|
const now = nextCreatedAt();
|
|
128
142
|
const result = await dbCreate(ARTICLES, {
|
|
129
143
|
slug,
|
|
@@ -175,6 +189,7 @@ async function filteredIds(options) {
|
|
|
175
189
|
if (options.tag) {
|
|
176
190
|
const rows = await findMany(ARTICLE_TAGS, {
|
|
177
191
|
where: [{ field: 'tag', operator: '=', value: options.tag }],
|
|
192
|
+
orderBy: TAGS_IN_ARTICLE_ORDER,
|
|
178
193
|
select: ['articleId'],
|
|
179
194
|
});
|
|
180
195
|
ids = rows.map((r) => r.articleId);
|
|
@@ -332,7 +347,11 @@ export async function setFavorite(slug, userId, favorite) {
|
|
|
332
347
|
* @returns Tags with their article counts.
|
|
333
348
|
*/
|
|
334
349
|
export async function popularTags(limit = 20) {
|
|
335
|
-
const rows = await findMany(ARTICLE_TAGS, {
|
|
350
|
+
const rows = await findMany(ARTICLE_TAGS, {
|
|
351
|
+
orderBy: TAGS_IN_ARTICLE_ORDER,
|
|
352
|
+
select: ['tag'],
|
|
353
|
+
limit: 50_000,
|
|
354
|
+
});
|
|
336
355
|
const counts = new Map();
|
|
337
356
|
for (const r of rows)
|
|
338
357
|
counts.set(r.tag, (counts.get(r.tag) ?? 0) + 1);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-resource-article",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.3",
|
|
4
4
|
"description": "Articles and blog posts: unique slugs, tags, favorites, a followed-authors feed, and filtered, paginated lists",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
],
|
|
34
34
|
"license": "Apache-2.0",
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@molecule/api-database": "1.0
|
|
37
|
-
"@molecule/api-database-sqlite": "1.
|
|
36
|
+
"@molecule/api-database": "1.1.0",
|
|
37
|
+
"@molecule/api-database-sqlite": "1.2.1",
|
|
38
38
|
"@molecule/api-resource-follow": "1.0.5",
|
|
39
39
|
"@molecule/api-resource-reaction": "1.0.3",
|
|
40
40
|
"@molecule/api-slug": "1.0.1",
|
|
@@ -17,6 +17,10 @@ CREATE TABLE IF NOT EXISTS "article_tags" (
|
|
|
17
17
|
"id" UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
18
18
|
"articleId" UUID NOT NULL REFERENCES "articles"("id") ON DELETE CASCADE,
|
|
19
19
|
"tag" VARCHAR(100) NOT NULL,
|
|
20
|
+
-- The order the tag was given in (0-based). Without it a reader of this table
|
|
21
|
+
-- gets the tags in whatever order the database returns rows, which is not the
|
|
22
|
+
-- order the article was submitted with.
|
|
23
|
+
"position" INTEGER NOT NULL DEFAULT 0,
|
|
20
24
|
"createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
|
|
21
25
|
UNIQUE ("articleId", "tag")
|
|
22
26
|
);
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
-- Tag order on an article: the column "article_tags"."position" keeps the order
|
|
2
|
+
-- the tags were given in, so a reader of the join table (a tag filter, an app's
|
|
3
|
+
-- own query) gets them in that order instead of the database's arbitrary row
|
|
4
|
+
-- order.
|
|
5
|
+
--
|
|
6
|
+
-- Why this is its own file: a database that already applied articles.sql never
|
|
7
|
+
-- re-runs it — "_molecule_migrations" records each setup file once — so the
|
|
8
|
+
-- column cannot be delivered by editing that file alone. This file is new, so it
|
|
9
|
+
-- runs on every database that has the table, whether it was created before or
|
|
10
|
+
-- after the column existed.
|
|
11
|
+
--
|
|
12
|
+
-- The CREATE repeats articles.sql's "article_tags" (see the test that keeps the
|
|
13
|
+
-- two in step). In a scaffolded app it is a no-op — articles.sql sorts first and
|
|
14
|
+
-- has already created the table, so the column below is what this file is for —
|
|
15
|
+
-- and it is what lets the scaffolding tool find the file at all: a setup file is
|
|
16
|
+
-- copied into a project through the table it declares.
|
|
17
|
+
CREATE TABLE IF NOT EXISTS "article_tags" (
|
|
18
|
+
"id" UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
19
|
+
"articleId" UUID NOT NULL REFERENCES "articles"("id") ON DELETE CASCADE,
|
|
20
|
+
"tag" VARCHAR(100) NOT NULL,
|
|
21
|
+
"position" INTEGER NOT NULL DEFAULT 0,
|
|
22
|
+
"createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
|
|
23
|
+
UNIQUE ("articleId", "tag")
|
|
24
|
+
);
|
|
25
|
+
|
|
26
|
+
-- The upgrade for a database whose "article_tags" predates the column. Every
|
|
27
|
+
-- database bond accepts this form: Postgres and PGlite take the clause natively,
|
|
28
|
+
-- and the SQLite and MySQL bonds apply the statement only when the column is not
|
|
29
|
+
-- there yet.
|
|
30
|
+
ALTER TABLE "article_tags" ADD COLUMN IF NOT EXISTS "position" INTEGER NOT NULL DEFAULT 0;
|