@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 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-15T09:18:33.058Z
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
- #### `Article`
69
+ #### `ArticleRow`
70
70
 
71
- An article as the service returns it: tags decoded, favorites counted, and
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 Article {
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, in the order they were given. */
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
- #### `ArticleRow`
96
+ #### `Article`
102
97
 
103
- An article row as stored. `tagList` is a JSON array of tag names.
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 ArticleRow {
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 (markdown or plain text — the app decides how to render it). */
111
+ /** Full body. */
116
112
  body: string
117
- /** Tag names, JSON-encoded. */
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, millisecond precision). */
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
- #### `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)`
237
+ #### `list(req, res)`
251
238
 
252
- `DELETE /articles/:slug` — author only.
239
+ `GET /articles` — newest first; `?tag=`, `?author=` (user id),
240
+ `?favoritedBy=` (user id), `?limit=`, `?offset=`.
253
241
 
254
242
  ```typescript
255
- function del(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
243
+ function list(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
256
244
  ```
257
245
 
258
246
  - `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.
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
- #### `findArticleRow(slug)`
260
+ #### `tags(req, res)`
286
261
 
287
- The stored row for a slug.
262
+ `GET /articles/tags` — tags in use, most-used first (`?limit=`).
288
263
 
289
264
  ```typescript
290
- function findArticleRow(slug: string): Promise<ArticleRow | null>
265
+ function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
291
266
  ```
292
267
 
293
- - `slug` — The article slug.
294
-
295
- **Returns:** The row, or null.
268
+ - `req` — The request.
269
+ - `res` — `[{ tag, count }]`.
296
270
 
297
- #### `getArticleBySlug(slug, viewerId)`
271
+ #### `read(req, res)`
298
272
 
299
- An article by slug.
273
+ `GET /articles/:slug`.
300
274
 
301
275
  ```typescript
302
- function getArticleBySlug(slug: string, viewerId?: string): Promise<Article | null>
276
+ function read(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
303
277
  ```
304
278
 
305
- - `slug` — The article slug.
306
- - `viewerId` — The viewing user, for `favorited`.
307
-
308
- **Returns:** The article, or null.
279
+ - `req` — The request.
280
+ - `res` — The article, or 404.
309
281
 
310
- #### `getFeed(userId, options)`
282
+ #### `update(req, res)`
311
283
 
312
- Articles by the users `userId` follows, newest first.
284
+ `PUT /articles/:slug` — author only; a new title gives a new slug.
313
285
 
314
286
  ```typescript
315
- function getFeed(
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
- - `userId` — The reader.
322
- - `options` — Paging.
290
+ - `req` — Body: any of `{ title, description, body, tagList }`.
291
+ - `res` — The updated article, 403 or 404.
323
292
 
324
- **Returns:** A page of articles and the total.
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
- #### `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)`
318
+ #### `createArticle(authorId, input)`
353
319
 
354
- Articles newest first, filtered by tag, author and who favorited them.
320
+ Create an article with a unique slug derived from its title.
355
321
 
356
322
  ```typescript
357
- function listArticles(options?: ListArticlesOptions): Promise<PaginatedArticles>
323
+ function createArticle(authorId: string, input: CreateArticleInput): Promise<Article>
358
324
  ```
359
325
 
360
- - `options` — Filters, paging and the viewer.
326
+ - `authorId` — The writing user.
327
+ - `input` — Title, body, optional description and tags.
361
328
 
362
- **Returns:** A page of articles and the total matching.
329
+ **Returns:** The created article.
363
330
 
364
- #### `popularTags(limit)`
331
+ #### `findArticleRow(slug)`
365
332
 
366
- Tags in use, most-used first.
333
+ The stored row for a slug.
367
334
 
368
335
  ```typescript
369
- function popularTags(limit?: number): Promise<TagCount[]>
336
+ function findArticleRow(slug: string): Promise<ArticleRow | null>
370
337
  ```
371
338
 
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
- ```
339
+ - `slug` — The article slug.
383
340
 
384
- - `req` — The request.
385
- - `res` — The article, or 404.
341
+ **Returns:** The row, or null.
386
342
 
387
- #### `setFavorite(slug, userId, favorite)`
343
+ #### `getArticleBySlug(slug, viewerId)`
388
344
 
389
- Favorite or unfavorite an article for a user (idempotent both ways).
345
+ An article by slug.
390
346
 
391
347
  ```typescript
392
- function setFavorite(slug: string, userId: string, favorite: boolean): Promise<Article | null>
348
+ function getArticleBySlug(slug: string, viewerId?: string): Promise<Article | null>
393
349
  ```
394
350
 
395
351
  - `slug` — The article slug.
396
- - `userId` — The user.
397
- - `favorite` — True to favorite, false to remove the favorite.
352
+ - `viewerId` — The viewing user, for `favorited`.
398
353
 
399
- **Returns:** The article after the change, or null when there is no such article.
354
+ **Returns:** The article, or null.
400
355
 
401
- #### `tags(req, res)`
356
+ #### `listArticles(options)`
402
357
 
403
- `GET /articles/tags` — tags in use, most-used first (`?limit=`).
358
+ Articles newest first, filtered by tag, author and who favorited them.
404
359
 
405
360
  ```typescript
406
- function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
361
+ function listArticles(options?: ListArticlesOptions): Promise<PaginatedArticles>
407
362
  ```
408
363
 
409
- - `req` — The request.
410
- - `res` — `[{ tag, count }]`.
364
+ - `options` — Filters, paging and the viewer.
411
365
 
412
- #### `update(req, res)`
366
+ **Returns:** A page of articles and the total matching.
413
367
 
414
- `PUT /articles/:slug` — author only; a new title gives a new slug.
368
+ #### `getFeed(userId, options)`
369
+
370
+ Articles by the users `userId` follows, newest first.
415
371
 
416
372
  ```typescript
417
- function update(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
373
+ function getFeed(
374
+ userId: string,
375
+ options?: { limit?: number; offset?: number },
376
+ ): Promise<PaginatedArticles>
418
377
  ```
419
378
 
420
- - `req` — Body: any of `{ title, description, body, tagList }`.
421
- - `res` — The updated article, 403 or 404.
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
- ### Constants
442
-
443
- #### `ARTICLE_RESOURCE_TYPE`
402
+ #### `deleteArticle(slug, userId)`
444
403
 
445
- The resource type favorites and comments on articles are stored under.
404
+ Delete an article and its tags and favorites. Only its author may.
446
405
 
447
406
  ```typescript
448
- const ARTICLE_RESOURCE_TYPE: 'article'
407
+ function deleteArticle(slug: string, userId: string): Promise<AuthorChange<true>>
449
408
  ```
450
409
 
451
- #### `createArticleSchema`
410
+ - `slug` — The article slug.
411
+ - `userId` — The requesting user.
452
412
 
453
- Schema for creating an article.
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
- 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
- >
420
+ function setFavorite(slug: string, userId: string, favorite: boolean): Promise<Article | null>
465
421
  ```
466
422
 
467
- #### `favorite`
423
+ - `slug` — The article slug.
424
+ - `userId` — The user.
425
+ - `favorite` — True to favorite, false to remove the favorite.
468
426
 
469
- `POST /articles/:slug/favorite` — idempotent; returns the article.
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
- const favorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
434
+ function popularTags(limit?: number): Promise<TagCount[]>
473
435
  ```
474
436
 
475
- #### `FAVORITE_REACTION`
437
+ - `limit` — How many to return (default 20).
476
438
 
477
- The reaction type a favorite is stored as.
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 FAVORITE_REACTION: 'favorite'
448
+ const favorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
481
449
  ```
482
450
 
483
- #### `MAX_ARTICLES_PAGE`
451
+ #### `unfavorite`
484
452
 
485
- Largest page a list returns.
453
+ `DELETE /articles/:slug/favorite` — idempotent; returns the article.
486
454
 
487
455
  ```typescript
488
- const MAX_ARTICLES_PAGE: 100
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
- #### `unfavorite`
525
+ #### `ARTICLE_RESOURCE_TYPE`
567
526
 
568
- `DELETE /articles/:slug/favorite` — idempotent; returns the article.
527
+ The resource type favorites and comments on articles are stored under.
569
528
 
570
529
  ```typescript
571
- const unfavorite: (req: MoleculeRequest, res: MoleculeResponse) => Promise<void>
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;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"}
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
@@ -1 +1 @@
1
- {"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,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;AAOD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBjG;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;AAiCD;;;;;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,CAQjE"}
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
- for (const tag of tags)
112
- await dbCreate(ARTICLE_TAGS, { articleId, tag });
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 by the column default: SQLite's CURRENT_TIMESTAMP
125
- // has whole seconds, so two articles from the same second tied and "newest
126
- // first" came back in either order; this one is unique per process.
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, { select: ['tag'], limit: 50_000 });
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.1",
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.2",
37
- "@molecule/api-database-sqlite": "1.0.5",
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;