@molecule/api-resource-article 1.0.7 → 1.1.1

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,15 +3,11 @@ 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-16T15:23:40.659Z
6
+ Generated: 2026-10-17T20:38:27.936Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-article
10
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
11
  Articles and blog posts for molecule.dev.
16
12
 
17
13
  Articles with unique slugs, tags, favorites, a feed of the authors a user
@@ -24,7 +20,11 @@ favorites and follows the rest of the app sees.
24
20
  **Tables this package owns: `articles` and `article_tags`.** The join between them is
25
21
  `article_tags.articleId` = `articles.id` (a declared FK, `ON DELETE CASCADE`; `("articleId", "tag")` is
26
22
  unique, and `article_tags.position` is the order the tags were given in). It also ships
27
- `reactions.sql` and `follows.sql`, which create the `reactions` and `follows` tables it reads by name.
23
+ `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
24
+
25
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
26
+ > It is written to be read by coding agents as much as by people, and is generated from this
27
+ > package's source — edit `src/index.ts` JSDoc, not this file.
28
28
 
29
29
  ## Quick Start
30
30
 
@@ -35,7 +35,7 @@ import { routes, requestHandlerMap } from '@molecule/api-resource-article'
35
35
  // POST /articles create (signed in)
36
36
  // GET /articles ?tag= &author= &favoritedBy= &limit= &offset=
37
37
  // GET /articles/feed authors the signed-in user follows
38
- // GET /articles/tags tags in use, most-used first
38
+ // GET /articles/tags every tag in use, most-used first (?limit= caps it)
39
39
  // GET /articles/:slug
40
40
  // PUT /articles/:slug author only; a new title gives a new slug
41
41
  // DELETE /articles/:slug author only
@@ -57,6 +57,16 @@ const page = await listArticles({ tag: 'dragons', limit: 20, offset: 0, viewerId
57
57
  // page.data[0].favorited, page.data[0].favoritesCount, page.total
58
58
  ```
59
59
 
60
+ ```typescript
61
+ // RealWorld's `GET /api/tags` returns EVERY tag in use — that is `allTags()`,
62
+ // not `popularTags()`, whose default is the top 20:
63
+ import { allTags } from '@molecule/api-resource-article'
64
+
65
+ router.get('/api/tags', async (_req, res) => {
66
+ res.json({ tags: (await allTags()).map((tag) => tag.tag) })
67
+ })
68
+ ```
69
+
60
70
  ## Type
61
71
 
62
72
  `resource`
@@ -264,13 +274,16 @@ function feed(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
264
274
 
265
275
  #### `tags(req, res)`
266
276
 
267
- `GET /articles/tags` — tags in use, most-used first (`?limit=`).
277
+ `GET /articles/tags` — every tag in use, most-used first.
278
+
279
+ With no `?limit=` this is the whole list, the shape RealWorld's `GET /tags`
280
+ asks for; `?limit=` narrows it to that many most-used tags.
268
281
 
269
282
  ```typescript
270
283
  function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
271
284
  ```
272
285
 
273
- - `req` — The request.
286
+ - `req` — The request; `?limit=` caps the list.
274
287
  - `res` — `[{ tag, count }]`.
275
288
 
276
289
  #### `read(req, res)`
@@ -431,17 +444,40 @@ function setFavorite(slug: string, userId: string, favorite: boolean): Promise<A
431
444
 
432
445
  **Returns:** The article after the change, or null when there is no such article.
433
446
 
447
+ #### `allTags()`
448
+
449
+ Every tag in use, most-used first (ties alphabetical).
450
+
451
+ This is the list a `GET /tags` endpoint returns, in the shape RealWorld's
452
+ `GET /api/tags` asks for: **all** of the tags in use, however many the
453
+ database holds. Use it for that endpoint — `popularTags` is the top-N
454
+ leaderboard and its default of 20 silently drops every tag past the
455
+ twentieth.
456
+
457
+ ```typescript
458
+ function allTags(): Promise<TagCount[]>
459
+ ```
460
+
461
+ **Returns:** Every tag in use, with its article count.
462
+
434
463
  #### `popularTags(limit)`
435
464
 
436
- Tags in use, most-used first.
465
+ The `limit` most-used tags, most-used first (ties alphabetical).
466
+
467
+ **This is a leaderboard, not "every tag".** The default is the top 20, so a
468
+ `GET /tags`-shaped endpoint that returns all tags in use (RealWorld's
469
+ `GET /api/tags`) must call `allTags` — or pass
470
+ `Number.POSITIVE_INFINITY` — or it silently drops every tag past the
471
+ twentieth once the database holds more than 20. Pass an explicit `limit`
472
+ when the caller really did ask for the N most-used, e.g. a sidebar of ten.
437
473
 
438
474
  ```typescript
439
475
  function popularTags(limit?: number): Promise<TagCount[]>
440
476
  ```
441
477
 
442
- - `limit` — How many to return (default 20).
478
+ - `limit` — How many tags to return, most-used first (default 20; `Number.POSITIVE_INFINITY` for every tag).
443
479
 
444
- **Returns:** Tags with their article counts.
480
+ **Returns:** The tags with their article counts.
445
481
 
446
482
  ### Constants
447
483
 
@@ -618,10 +654,12 @@ Peer dependencies:
618
654
  - `@molecule/api-slug`
619
655
  - `zod`
620
656
 
621
- - **Migration required: this package ships every table it reads, four in
622
- all.** `articles.sql` creates the `articles` and `article_tags` tables;
623
- `articles_position.sql` adds the `position` column to a database whose
624
- `article_tags` predates it; `reactions.sql` and `follows.sql` create the
657
+ - **A scaffold that lists this package already has these tables** — its `__setup__` SQL is
658
+ copied into the app at create time and replayed on every boot, so do not copy it into
659
+ `api/migrations/` yourself. This package ships every table it reads, four in
660
+ all. `src/__setup__/articles.sql` creates the `articles` and `article_tags` tables;
661
+ `src/__setup__/articles_position.sql` adds the `position` column to a database whose
662
+ `article_tags` predates it; `src/__setup__/reactions.sql` and `src/__setup__/follows.sql` create the
625
663
  `reactions` and `follows` tables, which this package reads directly by name
626
664
  on every response (favorites) and on its feed (who a reader follows). Those
627
665
  last two are copies of `@molecule/api-resource-reaction`'s and
@@ -630,12 +668,19 @@ Peer dependencies:
630
668
  installs those packages runs both copies harmlessly. A scaffold copies the
631
669
  tables a package's registry entry declares, and this one declares all four,
632
670
  so a project that installs only this package gets every table its endpoints
633
- need. Applying `articles.sql` alone leaves every article response failing
671
+ need. Applying `src/__setup__/articles.sql` alone leaves every article response failing
634
672
  with `no such table: reactions`.
635
673
  - **`article_tags` keeps the order the tags were given in**, in its `position`
636
674
  column (0-based). An app that reads the join table itself must order by
637
675
  `position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
638
676
  the wrong tag otherwise. `Article.tagList` is already in that order.
677
+ - **Tags: `allTags()` is every tag in use; `popularTags(limit)` is the top 20
678
+ by default.** A `GET /tags` endpoint (RealWorld's `GET /api/tags`, which
679
+ returns the whole list) built on `popularTags()` with no argument drops
680
+ every tag past the twentieth as soon as the database holds more than 20 —
681
+ call `allTags()` for that endpoint, and pass a `limit` only where the caller
682
+ asked for the N most-used. The package's own `GET /articles/tags` route does
683
+ exactly this: no `?limit=` is the whole list.
639
684
  - **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
640
685
  at most 100 per page. `createdAt` is written with milliseconds, so two
641
686
  articles from the same second still come back in order on SQLite.
@@ -27,9 +27,12 @@ export declare function list(req: MoleculeRequest, res: MoleculeResponse): Promi
27
27
  */
28
28
  export declare function feed(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
29
29
  /**
30
- * `GET /articles/tags` — tags in use, most-used first (`?limit=`).
30
+ * `GET /articles/tags` — every tag in use, most-used first.
31
31
  *
32
- * @param req - The request.
32
+ * With no `?limit=` this is the whole list, the shape RealWorld's `GET /tags`
33
+ * asks for; `?limit=` narrows it to that many most-used tags.
34
+ *
35
+ * @param req - The request; `?limit=` caps the list.
33
36
  * @param res - `[{ tag, count }]`.
34
37
  */
35
38
  export declare function tags(req: MoleculeRequest, res: MoleculeResponse): Promise<void>;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAwB/E;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvF;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASrF;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAcvF;AAED;;;;;GAKG;AACH,wBAAsB,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpF;AAiBD,yEAAyE;AACzE,eAAO,MAAM,QAAQ,QAdP,eAAe,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CActB,CAAA;AAE7C,2EAA2E;AAC3E,eAAO,MAAM,UAAU,QAjBT,eAAe,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAiBnB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAyB/E;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvF;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrF;AAED;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQrF;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASrF;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAcvF;AAED;;;;;GAKG;AACH,wBAAsB,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpF;AAiBD,yEAAyE;AACzE,eAAO,MAAM,QAAQ,QAdP,eAAe,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CActB,CAAA;AAE7C,2EAA2E;AAC3E,eAAO,MAAM,UAAU,QAjBT,eAAe,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAiBnB,CAAA"}
@@ -4,7 +4,7 @@
4
4
  * @module
5
5
  */
6
6
  import { logger } from '@molecule/api-logger';
7
- import { createArticle, deleteArticle, getArticleBySlug, getFeed, listArticles, popularTags, setFavorite, updateArticle, } from '../service.js';
7
+ import { allTags, createArticle, deleteArticle, getArticleBySlug, getFeed, listArticles, popularTags, setFavorite, updateArticle, } from '../service.js';
8
8
  import { createArticleSchema, updateArticleSchema } from '../validation.js';
9
9
  import { failed, forbidden, invalid, notFound, queryInt, queryString, sessionUserId, unauthorized, } from './shared.js';
10
10
  /**
@@ -73,14 +73,18 @@ export async function feed(req, res) {
73
73
  }
74
74
  }
75
75
  /**
76
- * `GET /articles/tags` — tags in use, most-used first (`?limit=`).
76
+ * `GET /articles/tags` — every tag in use, most-used first.
77
77
  *
78
- * @param req - The request.
78
+ * With no `?limit=` this is the whole list, the shape RealWorld's `GET /tags`
79
+ * asks for; `?limit=` narrows it to that many most-used tags.
80
+ *
81
+ * @param req - The request; `?limit=` caps the list.
79
82
  * @param res - `[{ tag, count }]`.
80
83
  */
81
84
  export async function tags(req, res) {
82
85
  try {
83
- res.json(await popularTags(queryInt(req.query.limit)));
86
+ const limit = queryInt(req.query.limit);
87
+ res.json(limit === undefined ? await allTags() : await popularTags(limit));
84
88
  }
85
89
  catch (error) {
86
90
  logger.error('Failed to list article tags', { error });
package/dist/index.d.ts CHANGED
@@ -11,7 +11,7 @@
11
11
  * **Tables this package owns: `articles` and `article_tags`.** The join between them is
12
12
  * `article_tags.articleId` = `articles.id` (a declared FK, `ON DELETE CASCADE`; `("articleId", "tag")` is
13
13
  * unique, and `article_tags.position` is the order the tags were given in). It also ships
14
- * `reactions.sql` and `follows.sql`, which create the `reactions` and `follows` tables it reads by name.
14
+ * `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
15
15
  *
16
16
  * @module
17
17
  * @example
@@ -22,7 +22,7 @@
22
22
  * // POST /articles create (signed in)
23
23
  * // GET /articles ?tag= &author= &favoritedBy= &limit= &offset=
24
24
  * // GET /articles/feed authors the signed-in user follows
25
- * // GET /articles/tags tags in use, most-used first
25
+ * // GET /articles/tags every tag in use, most-used first (?limit= caps it)
26
26
  * // GET /articles/:slug
27
27
  * // PUT /articles/:slug author only; a new title gives a new slug
28
28
  * // DELETE /articles/:slug author only
@@ -45,11 +45,22 @@
45
45
  * // page.data[0].favorited, page.data[0].favoritesCount, page.total
46
46
  * ```
47
47
  *
48
+ * @example
49
+ * ```typescript
50
+ * // RealWorld's `GET /api/tags` returns EVERY tag in use — that is `allTags()`,
51
+ * // not `popularTags()`, whose default is the top 20:
52
+ * import { allTags } from '@molecule/api-resource-article'
53
+ *
54
+ * router.get('/api/tags', async (_req, res) => {
55
+ * res.json({ tags: (await allTags()).map((tag) => tag.tag) })
56
+ * })
57
+ * ```
58
+ *
48
59
  * @remarks
49
60
  * - **Migration required: this package ships every table it reads, four in
50
- * all.** `articles.sql` creates the `articles` and `article_tags` tables;
51
- * `articles_position.sql` adds the `position` column to a database whose
52
- * `article_tags` predates it; `reactions.sql` and `follows.sql` create the
61
+ * all.** `src/__setup__/articles.sql` creates the `articles` and `article_tags` tables;
62
+ * `src/__setup__/articles_position.sql` adds the `position` column to a database whose
63
+ * `article_tags` predates it; `src/__setup__/reactions.sql` and `src/__setup__/follows.sql` create the
53
64
  * `reactions` and `follows` tables, which this package reads directly by name
54
65
  * on every response (favorites) and on its feed (who a reader follows). Those
55
66
  * last two are copies of `@molecule/api-resource-reaction`'s and
@@ -58,12 +69,19 @@
58
69
  * installs those packages runs both copies harmlessly. A scaffold copies the
59
70
  * tables a package's registry entry declares, and this one declares all four,
60
71
  * so a project that installs only this package gets every table its endpoints
61
- * need. Applying `articles.sql` alone leaves every article response failing
72
+ * need. Applying `src/__setup__/articles.sql` alone leaves every article response failing
62
73
  * with `no such table: reactions`.
63
74
  * - **`article_tags` keeps the order the tags were given in**, in its `position`
64
75
  * column (0-based). An app that reads the join table itself must order by
65
76
  * `position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
66
77
  * the wrong tag otherwise. `Article.tagList` is already in that order.
78
+ * - **Tags: `allTags()` is every tag in use; `popularTags(limit)` is the top 20
79
+ * by default.** A `GET /tags` endpoint (RealWorld's `GET /api/tags`, which
80
+ * returns the whole list) built on `popularTags()` with no argument drops
81
+ * every tag past the twentieth as soon as the database holds more than 20 —
82
+ * call `allTags()` for that endpoint, and pass a `limit` only where the caller
83
+ * asked for the N most-used. The package's own `GET /articles/tags` route does
84
+ * exactly this: no `?limit=` is the whole list.
67
85
  * - **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
68
86
  * at most 100 per page. `createdAt` is written with milliseconds, so two
69
87
  * articles from the same second still come back in order on SQLite.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;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
@@ -11,7 +11,7 @@
11
11
  * **Tables this package owns: `articles` and `article_tags`.** The join between them is
12
12
  * `article_tags.articleId` = `articles.id` (a declared FK, `ON DELETE CASCADE`; `("articleId", "tag")` is
13
13
  * unique, and `article_tags.position` is the order the tags were given in). It also ships
14
- * `reactions.sql` and `follows.sql`, which create the `reactions` and `follows` tables it reads by name.
14
+ * `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
15
15
  *
16
16
  * @module
17
17
  * @example
@@ -22,7 +22,7 @@
22
22
  * // POST /articles create (signed in)
23
23
  * // GET /articles ?tag= &author= &favoritedBy= &limit= &offset=
24
24
  * // GET /articles/feed authors the signed-in user follows
25
- * // GET /articles/tags tags in use, most-used first
25
+ * // GET /articles/tags every tag in use, most-used first (?limit= caps it)
26
26
  * // GET /articles/:slug
27
27
  * // PUT /articles/:slug author only; a new title gives a new slug
28
28
  * // DELETE /articles/:slug author only
@@ -45,11 +45,22 @@
45
45
  * // page.data[0].favorited, page.data[0].favoritesCount, page.total
46
46
  * ```
47
47
  *
48
+ * @example
49
+ * ```typescript
50
+ * // RealWorld's `GET /api/tags` returns EVERY tag in use — that is `allTags()`,
51
+ * // not `popularTags()`, whose default is the top 20:
52
+ * import { allTags } from '@molecule/api-resource-article'
53
+ *
54
+ * router.get('/api/tags', async (_req, res) => {
55
+ * res.json({ tags: (await allTags()).map((tag) => tag.tag) })
56
+ * })
57
+ * ```
58
+ *
48
59
  * @remarks
49
60
  * - **Migration required: this package ships every table it reads, four in
50
- * all.** `articles.sql` creates the `articles` and `article_tags` tables;
51
- * `articles_position.sql` adds the `position` column to a database whose
52
- * `article_tags` predates it; `reactions.sql` and `follows.sql` create the
61
+ * all.** `src/__setup__/articles.sql` creates the `articles` and `article_tags` tables;
62
+ * `src/__setup__/articles_position.sql` adds the `position` column to a database whose
63
+ * `article_tags` predates it; `src/__setup__/reactions.sql` and `src/__setup__/follows.sql` create the
53
64
  * `reactions` and `follows` tables, which this package reads directly by name
54
65
  * on every response (favorites) and on its feed (who a reader follows). Those
55
66
  * last two are copies of `@molecule/api-resource-reaction`'s and
@@ -58,12 +69,19 @@
58
69
  * installs those packages runs both copies harmlessly. A scaffold copies the
59
70
  * tables a package's registry entry declares, and this one declares all four,
60
71
  * so a project that installs only this package gets every table its endpoints
61
- * need. Applying `articles.sql` alone leaves every article response failing
72
+ * need. Applying `src/__setup__/articles.sql` alone leaves every article response failing
62
73
  * with `no such table: reactions`.
63
74
  * - **`article_tags` keeps the order the tags were given in**, in its `position`
64
75
  * column (0-based). An app that reads the join table itself must order by
65
76
  * `position` — a submission-order assertion (`tagList[0]`, `tagList[1]`) reads
66
77
  * the wrong tag otherwise. `Article.tagList` is already in that order.
78
+ * - **Tags: `allTags()` is every tag in use; `popularTags(limit)` is the top 20
79
+ * by default.** A `GET /tags` endpoint (RealWorld's `GET /api/tags`, which
80
+ * returns the whole list) built on `popularTags()` with no argument drops
81
+ * every tag past the twentieth as soon as the database holds more than 20 —
82
+ * call `allTags()` for that endpoint, and pass a `limit` only where the caller
83
+ * asked for the N most-used. The package's own `GET /articles/tags` route does
84
+ * exactly this: no `?limit=` is the whole list.
67
85
  * - **Lists are newest first and paginated** — `{ data, total, limit, offset }`,
68
86
  * at most 100 per page. `createdAt` is written with milliseconds, so two
69
87
  * articles from the same second still come back in order on SQLite.
package/dist/service.d.ts CHANGED
@@ -108,10 +108,29 @@ export declare function deleteArticle(slug: string, userId: string): Promise<Aut
108
108
  */
109
109
  export declare function setFavorite(slug: string, userId: string, favorite: boolean): Promise<Article | null>;
110
110
  /**
111
- * Tags in use, most-used first.
111
+ * Every tag in use, most-used first (ties alphabetical).
112
112
  *
113
- * @param limit - How many to return (default 20).
114
- * @returns Tags with their article counts.
113
+ * This is the list a `GET /tags` endpoint returns, in the shape RealWorld's
114
+ * `GET /api/tags` asks for: **all** of the tags in use, however many the
115
+ * database holds. Use it for that endpoint — `popularTags` is the top-N
116
+ * leaderboard and its default of 20 silently drops every tag past the
117
+ * twentieth.
118
+ *
119
+ * @returns Every tag in use, with its article count.
120
+ */
121
+ export declare function allTags(): Promise<TagCount[]>;
122
+ /**
123
+ * The `limit` most-used tags, most-used first (ties alphabetical).
124
+ *
125
+ * **This is a leaderboard, not "every tag".** The default is the top 20, so a
126
+ * `GET /tags`-shaped endpoint that returns all tags in use (RealWorld's
127
+ * `GET /api/tags`) must call `allTags` — or pass
128
+ * `Number.POSITIVE_INFINITY` — or it silently drops every tag past the
129
+ * twentieth once the database holds more than 20. Pass an explicit `limit`
130
+ * when the caller really did ask for the N most-used, e.g. a sidebar of ten.
131
+ *
132
+ * @param limit - How many tags to return, most-used first (default 20; `Number.POSITIVE_INFINITY` for every tag).
133
+ * @returns The tags with their article counts.
115
134
  */
116
135
  export declare function popularTags(limit?: number): Promise<TagCount[]>;
117
136
  //# sourceMappingURL=service.d.ts.map
@@ -1 +1 @@
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;AA0CpF,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"}
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;AA0CpF,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;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAEnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAEjE"}
package/dist/service.js CHANGED
@@ -353,12 +353,41 @@ export async function setFavorite(slug, userId, favorite) {
353
353
  return article;
354
354
  }
355
355
  /**
356
- * Tags in use, most-used first.
356
+ * Every tag in use, most-used first (ties alphabetical).
357
357
  *
358
- * @param limit - How many to return (default 20).
359
- * @returns Tags with their article counts.
358
+ * This is the list a `GET /tags` endpoint returns, in the shape RealWorld's
359
+ * `GET /api/tags` asks for: **all** of the tags in use, however many the
360
+ * database holds. Use it for that endpoint — `popularTags` is the top-N
361
+ * leaderboard and its default of 20 silently drops every tag past the
362
+ * twentieth.
363
+ *
364
+ * @returns Every tag in use, with its article count.
365
+ */
366
+ export async function allTags() {
367
+ return countTagRows();
368
+ }
369
+ /**
370
+ * The `limit` most-used tags, most-used first (ties alphabetical).
371
+ *
372
+ * **This is a leaderboard, not "every tag".** The default is the top 20, so a
373
+ * `GET /tags`-shaped endpoint that returns all tags in use (RealWorld's
374
+ * `GET /api/tags`) must call `allTags` — or pass
375
+ * `Number.POSITIVE_INFINITY` — or it silently drops every tag past the
376
+ * twentieth once the database holds more than 20. Pass an explicit `limit`
377
+ * when the caller really did ask for the N most-used, e.g. a sidebar of ten.
378
+ *
379
+ * @param limit - How many tags to return, most-used first (default 20; `Number.POSITIVE_INFINITY` for every tag).
380
+ * @returns The tags with their article counts.
360
381
  */
361
382
  export async function popularTags(limit = 20) {
383
+ return (await countTagRows()).slice(0, Math.max(1, limit));
384
+ }
385
+ /**
386
+ * Tags in use with their article counts, most-used first (ties alphabetical).
387
+ *
388
+ * @returns Every tag in use.
389
+ */
390
+ const countTagRows = async () => {
362
391
  const rows = await findMany(ARTICLE_TAGS, {
363
392
  orderBy: TAGS_IN_ARTICLE_ORDER,
364
393
  select: ['tag'],
@@ -369,6 +398,5 @@ export async function popularTags(limit = 20) {
369
398
  counts.set(r.tag, (counts.get(r.tag) ?? 0) + 1);
370
399
  return [...counts.entries()]
371
400
  .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
372
- .slice(0, Math.max(1, limit))
373
401
  .map(([tag, n]) => ({ tag, count: n }));
374
- }
402
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-article",
3
- "version": "1.0.7",
3
+ "version": "1.1.1",
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",
@@ -34,7 +34,7 @@
34
34
  "license": "Apache-2.0",
35
35
  "devDependencies": {
36
36
  "@molecule/api-database": "1.1.3",
37
- "@molecule/api-database-sqlite": "1.2.4",
37
+ "@molecule/api-database-sqlite": "1.2.6",
38
38
  "@molecule/api-resource-follow": "1.0.7",
39
39
  "@molecule/api-resource-reaction": "1.0.4",
40
40
  "@molecule/api-slug": "1.0.1",