@molecule/api-resource-article 1.3.0 → 1.3.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,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-11-17T00:12:43.037Z
6
+ Generated: 2026-11-19T03:20:24.668Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-article
@@ -22,7 +22,7 @@ favorites and follows the rest of the app sees.
22
22
  unique, and `article_tags.position` is the order the tags were given in). It also ships
23
23
  `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
24
24
 
25
- **HTTP format is configuration.** In the scaffold's `App/Resource/Article/index.ts`,
25
+ **Reuse the article tables for custom routes.** In the scaffold's `App/Resource/Article/index.ts`,
26
26
  export `requestHandlerMap = createArticleHandlers({ mapRequest, mapResponse })`.
27
27
  Keep `create`, `list`, `feed`, `read`, `update`, `del`, `favorite`, `unfavorite`
28
28
  and `tags` in the package.
@@ -37,7 +37,11 @@ Join those maps while projecting the page. This keeps the page at two relationsh
37
37
  queries even when many entries share an author; per-entry lookups repeat the same work.
38
38
 
39
39
  ```typescript
40
- import { createArticleHandlers } from '@molecule/api-resource-article'
40
+ import {
41
+ createArticleHandlers,
42
+ listArticles,
43
+ type ListArticlesOptions,
44
+ } from '@molecule/api-resource-article'
41
45
 
42
46
  export const requestHandlerMap = createArticleHandlers({
43
47
  mapRequest: (req) => ({ body: req.body?.entry }),
@@ -46,12 +50,25 @@ export const requestHandlerMap = createArticleHandlers({
46
50
  ? result
47
51
  : { ...result, body: { entry: result.body } },
48
52
  })
53
+
54
+ // For a custom list route, resolve public handles to user ids in the app.
55
+ // Pass those ids as authorId and favoritedBy, and the current reader as viewerId.
56
+ export async function listEntryPreviews(filters: ListArticlesOptions) {
57
+ const { data, total } = await listArticles(filters)
58
+ return {
59
+ entries: data.map(({ id, slug, title, favorited }) => ({ id, slug, title, favorited })),
60
+ entriesCount: total,
61
+ }
62
+ }
49
63
  ```
50
64
 
51
65
  Use the resulting map's handlers on the app's routes. For distinct route projections,
52
66
  create separate maps with separate options. The static `requestHandlerMap` keeps the
53
- native flat-body/raw-article format. Use service functions for a different domain workflow.
54
- Read Quick Start for filter mapping and early responses.
67
+ native flat-body/raw-article format. A list can combine tag, author and favorites
68
+ filters with limit and offset. When a requested handle cannot be resolved, return an
69
+ empty page instead of omitting its filter. `getFeed(viewerId, { limit, offset })`
70
+ handles the followed-author view. The services read the package's tables, so a
71
+ differently named table with its own schema needs its own persistence.
55
72
 
56
73
  **Need only a lookup in a custom route?** `findArticleRow(slug)` returns the stored
57
74
  `ArticleRow` or `null`. `getArticleBySlug(slug, viewerId?)` returns an `Article` or
package/dist/index.d.ts CHANGED
@@ -13,7 +13,7 @@
13
13
  * unique, and `article_tags.position` is the order the tags were given in). It also ships
14
14
  * `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
15
15
  *
16
- * **HTTP format is configuration.** In the scaffold's `App/Resource/Article/index.ts`,
16
+ * **Reuse the article tables for custom routes.** In the scaffold's `App/Resource/Article/index.ts`,
17
17
  * export `requestHandlerMap = createArticleHandlers({ mapRequest, mapResponse })`.
18
18
  * Keep `create`, `list`, `feed`, `read`, `update`, `del`, `favorite`, `unfavorite`
19
19
  * and `tags` in the package.
@@ -28,7 +28,7 @@
28
28
  * queries even when many entries share an author; per-entry lookups repeat the same work.
29
29
  *
30
30
  * ```typescript
31
- * import { createArticleHandlers } from '@molecule/api-resource-article'
31
+ * import { createArticleHandlers, listArticles, type ListArticlesOptions } from '@molecule/api-resource-article'
32
32
  *
33
33
  * export const requestHandlerMap = createArticleHandlers({
34
34
  * mapRequest: (req) => ({ body: req.body?.entry }),
@@ -36,12 +36,25 @@
36
36
  * ? result
37
37
  * : { ...result, body: { entry: result.body } },
38
38
  * })
39
+ *
40
+ * // For a custom list route, resolve public handles to user ids in the app.
41
+ * // Pass those ids as authorId and favoritedBy, and the current reader as viewerId.
42
+ * export async function listEntryPreviews(filters: ListArticlesOptions) {
43
+ * const { data, total } = await listArticles(filters)
44
+ * return {
45
+ * entries: data.map(({ id, slug, title, favorited }) => ({ id, slug, title, favorited })),
46
+ * entriesCount: total,
47
+ * }
48
+ * }
39
49
  * ```
40
50
  *
41
51
  * Use the resulting map's handlers on the app's routes. For distinct route projections,
42
52
  * create separate maps with separate options. The static `requestHandlerMap` keeps the
43
- * native flat-body/raw-article format. Use service functions for a different domain workflow.
44
- * Read Quick Start for filter mapping and early responses.
53
+ * native flat-body/raw-article format. A list can combine tag, author and favorites
54
+ * filters with limit and offset. When a requested handle cannot be resolved, return an
55
+ * empty page instead of omitting its filter. `getFeed(viewerId, { limit, offset })`
56
+ * handles the followed-author view. The services read the package's tables, so a
57
+ * differently named table with its own schema needs its own persistence.
45
58
  *
46
59
  * **Need only a lookup in a custom route?** `findArticleRow(slug)` returns the stored
47
60
  * `ArticleRow` or `null`. `getArticleBySlug(slug, viewerId?)` returns an `Article` or
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsLG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmMG;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
@@ -13,7 +13,7 @@
13
13
  * unique, and `article_tags.position` is the order the tags were given in). It also ships
14
14
  * `src/__setup__/reactions.sql` and `src/__setup__/follows.sql`, which create the `reactions` and `follows` tables it reads by name.
15
15
  *
16
- * **HTTP format is configuration.** In the scaffold's `App/Resource/Article/index.ts`,
16
+ * **Reuse the article tables for custom routes.** In the scaffold's `App/Resource/Article/index.ts`,
17
17
  * export `requestHandlerMap = createArticleHandlers({ mapRequest, mapResponse })`.
18
18
  * Keep `create`, `list`, `feed`, `read`, `update`, `del`, `favorite`, `unfavorite`
19
19
  * and `tags` in the package.
@@ -28,7 +28,7 @@
28
28
  * queries even when many entries share an author; per-entry lookups repeat the same work.
29
29
  *
30
30
  * ```typescript
31
- * import { createArticleHandlers } from '@molecule/api-resource-article'
31
+ * import { createArticleHandlers, listArticles, type ListArticlesOptions } from '@molecule/api-resource-article'
32
32
  *
33
33
  * export const requestHandlerMap = createArticleHandlers({
34
34
  * mapRequest: (req) => ({ body: req.body?.entry }),
@@ -36,12 +36,25 @@
36
36
  * ? result
37
37
  * : { ...result, body: { entry: result.body } },
38
38
  * })
39
+ *
40
+ * // For a custom list route, resolve public handles to user ids in the app.
41
+ * // Pass those ids as authorId and favoritedBy, and the current reader as viewerId.
42
+ * export async function listEntryPreviews(filters: ListArticlesOptions) {
43
+ * const { data, total } = await listArticles(filters)
44
+ * return {
45
+ * entries: data.map(({ id, slug, title, favorited }) => ({ id, slug, title, favorited })),
46
+ * entriesCount: total,
47
+ * }
48
+ * }
39
49
  * ```
40
50
  *
41
51
  * Use the resulting map's handlers on the app's routes. For distinct route projections,
42
52
  * create separate maps with separate options. The static `requestHandlerMap` keeps the
43
- * native flat-body/raw-article format. Use service functions for a different domain workflow.
44
- * Read Quick Start for filter mapping and early responses.
53
+ * native flat-body/raw-article format. A list can combine tag, author and favorites
54
+ * filters with limit and offset. When a requested handle cannot be resolved, return an
55
+ * empty page instead of omitting its filter. `getFeed(viewerId, { limit, offset })`
56
+ * handles the followed-author view. The services read the package's tables, so a
57
+ * differently named table with its own schema needs its own persistence.
45
58
  *
46
59
  * **Need only a lookup in a custom route?** `findArticleRow(slug)` returns the stored
47
60
  * `ArticleRow` or `null`. `getArticleBySlug(slug, viewerId?)` returns an `Article` or
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-article",
3
- "version": "1.3.0",
3
+ "version": "1.3.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",
@@ -35,9 +35,9 @@
35
35
  "devDependencies": {
36
36
  "@molecule/api-database": "1.2.2",
37
37
  "@molecule/api-database-sqlite": "1.4.3",
38
- "@molecule/api-resource-follow": "1.1.2",
38
+ "@molecule/api-resource-follow": "1.1.3",
39
39
  "@molecule/api-resource-reaction": "1.0.8",
40
- "@molecule/api-slug": "1.0.3",
40
+ "@molecule/api-slug": "1.0.4",
41
41
  "@types/express": "5.0.6",
42
42
  "@types/node": "26.6.5",
43
43
  "express": "5.3.0",