@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 +62 -17
- package/dist/handlers/index.d.ts +5 -2
- package/dist/handlers/index.d.ts.map +1 -1
- package/dist/handlers/index.js +8 -4
- package/dist/index.d.ts +24 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +24 -6
- package/dist/service.d.ts +22 -3
- package/dist/service.d.ts.map +1 -1
- package/dist/service.js +33 -5
- package/package.json +2 -2
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-
|
|
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
|
|
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` —
|
|
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
|
-
|
|
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:**
|
|
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
|
-
- **
|
|
622
|
-
|
|
623
|
-
`
|
|
624
|
-
`
|
|
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.
|
package/dist/handlers/index.d.ts
CHANGED
|
@@ -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` —
|
|
30
|
+
* `GET /articles/tags` — every tag in use, most-used first.
|
|
31
31
|
*
|
|
32
|
-
*
|
|
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;
|
|
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"}
|
package/dist/handlers/index.js
CHANGED
|
@@ -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` —
|
|
76
|
+
* `GET /articles/tags` — every tag in use, most-used first.
|
|
77
77
|
*
|
|
78
|
-
*
|
|
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
|
-
|
|
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
|
|
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/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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
|
|
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
|
-
*
|
|
111
|
+
* Every tag in use, most-used first (ties alphabetical).
|
|
112
112
|
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
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
|
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;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
|
|
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
|
-
*
|
|
356
|
+
* Every tag in use, most-used first (ties alphabetical).
|
|
357
357
|
*
|
|
358
|
-
*
|
|
359
|
-
*
|
|
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.
|
|
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.
|
|
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",
|