@molecule/api-resource-article 1.2.7 → 1.3.0

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-15T03:10:10.469Z
6
+ Generated: 2026-11-17T00:12:43.037Z
7
7
  -->
8
8
 
9
9
  # @molecule/api-resource-article
@@ -58,6 +58,13 @@ Read Quick Start for filter mapping and early responses.
58
58
  `null`, with ordered tags, favorite count and the viewer's `favorited` state.
59
59
  Both read this package's `articles` table. Keep your route, author-profile lookup
60
60
  and response projection local; call these functions instead of copying the slug query.
61
+ `uniqueArticleSlug(title, excludeId?)` exposes the same free-slug policy used by
62
+ `createArticle` and `updateArticle`, including reserved route words and the
63
+ `article` fallback. Use it for a custom workflow that needs a slug before writing;
64
+ use `createArticle` for a normal create. It checks availability without reserving
65
+ a slug, so retain the UNIQUE index and retry a conflicting insert. A different
66
+ table can use `uniqueSlugInTable(table, column, title, { excludeId })` from
67
+ `@molecule/api-slug`; its general policy does not reserve this resource's routes.
61
68
 
62
69
  ```typescript
63
70
  import { findArticleRow } from '@molecule/api-resource-article'
@@ -322,6 +329,23 @@ function createArticleHandlers(options?: RequestHandlerOptions): ArticleRequestH
322
329
 
323
330
  **Returns:** A route-compatible map with the same names as requestHandlerMap.
324
331
 
332
+ #### `uniqueArticleSlug(title, excludeId)`
333
+
334
+ Find a free slug in this package's articles table without writing an article.
335
+ Uses the same normalization, reserved route slugs and fallback as createArticle
336
+ and updateArticle. This is a lookup, not a reservation: keep the table's UNIQUE
337
+ index and retry a conflicting insert. For another table use api-slug's
338
+ uniqueSlugInTable instead.
339
+
340
+ ```typescript
341
+ function uniqueArticleSlug(title: string, excludeId?: string): Promise<string>
342
+ ```
343
+
344
+ - `title` — The article title.
345
+ - `excludeId` — The existing article's id, so it may keep its own slug on update.
346
+
347
+ **Returns:** An unused article slug; empty normalized titles use `article`.
348
+
325
349
  #### `hydrateArticles(rows, viewerId)`
326
350
 
327
351
  Turn stored rows into {@link Article}s: decoded tags, favorite counts and the
package/dist/index.d.ts CHANGED
@@ -48,6 +48,13 @@
48
48
  * `null`, with ordered tags, favorite count and the viewer's `favorited` state.
49
49
  * Both read this package's `articles` table. Keep your route, author-profile lookup
50
50
  * and response projection local; call these functions instead of copying the slug query.
51
+ * `uniqueArticleSlug(title, excludeId?)` exposes the same free-slug policy used by
52
+ * `createArticle` and `updateArticle`, including reserved route words and the
53
+ * `article` fallback. Use it for a custom workflow that needs a slug before writing;
54
+ * use `createArticle` for a normal create. It checks availability without reserving
55
+ * a slug, so retain the UNIQUE index and retry a conflicting insert. A different
56
+ * table can use `uniqueSlugInTable(table, column, title, { excludeId })` from
57
+ * `@molecule/api-slug`; its general policy does not reserve this resource's routes.
51
58
  *
52
59
  * ```typescript
53
60
  * import { findArticleRow } from '@molecule/api-resource-article'
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+KG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
package/dist/index.js CHANGED
@@ -48,6 +48,13 @@
48
48
  * `null`, with ordered tags, favorite count and the viewer's `favorited` state.
49
49
  * Both read this package's `articles` table. Keep your route, author-profile lookup
50
50
  * and response projection local; call these functions instead of copying the slug query.
51
+ * `uniqueArticleSlug(title, excludeId?)` exposes the same free-slug policy used by
52
+ * `createArticle` and `updateArticle`, including reserved route words and the
53
+ * `article` fallback. Use it for a custom workflow that needs a slug before writing;
54
+ * use `createArticle` for a normal create. It checks availability without reserving
55
+ * a slug, so retain the UNIQUE index and retry a conflicting insert. A different
56
+ * table can use `uniqueSlugInTable(table, column, title, { excludeId })` from
57
+ * `@molecule/api-slug`; its general policy does not reserve this resource's routes.
51
58
  *
52
59
  * ```typescript
53
60
  * import { findArticleRow } from '@molecule/api-resource-article'
package/dist/service.d.ts CHANGED
@@ -20,6 +20,18 @@ export declare const FAVORITE_REACTION = "favorite";
20
20
  * article titled "Feed" gets `feed-2`, or its page would be unreachable.
21
21
  */
22
22
  export declare const RESERVED_ARTICLE_SLUGS: ReadonlySet<string>;
23
+ /**
24
+ * Find a free slug in this package's articles table without writing an article.
25
+ * Uses the same normalization, reserved route slugs and fallback as createArticle
26
+ * and updateArticle. This is a lookup, not a reservation: keep the table's UNIQUE
27
+ * index and retry a conflicting insert. For another table use api-slug's
28
+ * uniqueSlugInTable instead.
29
+ *
30
+ * @param title - The article title.
31
+ * @param excludeId - The existing article's id, so it may keep its own slug on update.
32
+ * @returns An unused article slug; empty normalized titles use `article`.
33
+ */
34
+ export declare function uniqueArticleSlug(title: string, excludeId?: string): Promise<string>;
23
35
  /** Largest page a list returns. */
24
36
  export declare const MAX_ARTICLES_PAGE = 100;
25
37
  /**
@@ -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,CACnC,IAAI,EAAE,UAAU,EAAE,EAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,EAAE,CAAC,CA6BpB;AAsBD;;;;;;;;;;GAUG;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,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAKzB;AAkCD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoBhG;AAED;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;GAWG;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"}
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;AAEpF;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYpF;AA4BD,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAyBpC;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAAE,EAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,EAAE,CAAC,CA6BpB;AAsBD;;;;;;;;;;GAUG;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,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAKzB;AAkCD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoBhG;AAED;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;GAWG;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
@@ -26,15 +26,27 @@ export const FAVORITE_REACTION = 'favorite';
26
26
  * article titled "Feed" gets `feed-2`, or its page would be unreachable.
27
27
  */
28
28
  export const RESERVED_ARTICLE_SLUGS = new Set(['feed', 'tags']);
29
- /** A free slug for a title; `excludeId` lets an article keep its own on update. */
30
- const articleSlug = (title, excludeId) => uniqueSlug(title, async (slug) => {
31
- if (RESERVED_ARTICLE_SLUGS.has(slug))
32
- return true;
33
- const row = await findOne(ARTICLES, [
34
- { field: 'slug', operator: '=', value: slug },
35
- ]);
36
- return row != null && row.id !== excludeId;
37
- }, { fallback: 'article' });
29
+ /**
30
+ * Find a free slug in this package's articles table without writing an article.
31
+ * Uses the same normalization, reserved route slugs and fallback as createArticle
32
+ * and updateArticle. This is a lookup, not a reservation: keep the table's UNIQUE
33
+ * index and retry a conflicting insert. For another table use api-slug's
34
+ * uniqueSlugInTable instead.
35
+ *
36
+ * @param title - The article title.
37
+ * @param excludeId - The existing article's id, so it may keep its own slug on update.
38
+ * @returns An unused article slug; empty normalized titles use `article`.
39
+ */
40
+ export function uniqueArticleSlug(title, excludeId) {
41
+ return uniqueSlug(title, async (slug) => {
42
+ if (RESERVED_ARTICLE_SLUGS.has(slug))
43
+ return true;
44
+ const row = await findOne(ARTICLES, [
45
+ { field: 'slug', operator: '=', value: slug },
46
+ ]);
47
+ return row != null && row.id !== excludeId;
48
+ }, { fallback: 'article' });
49
+ }
38
50
  let lastCreatedMs = 0;
39
51
  /**
40
52
  * A creation time later than every earlier one from this process: two
@@ -148,7 +160,7 @@ const writeTags = async (articleId, tags) => {
148
160
  * @returns The created article.
149
161
  */
150
162
  export async function createArticle(authorId, input) {
151
- const slug = await articleSlug(input.title);
163
+ const slug = await uniqueArticleSlug(input.title);
152
164
  const tags = cleanTags(input.tagList);
153
165
  // Written here rather than left to the column default: the default is
154
166
  // millisecond-precision, so two articles created inside the same millisecond
@@ -312,7 +324,7 @@ export async function updateArticle(slug, userId, input) {
312
324
  const patch = { updatedAt: nextUpdatedAt(row.updatedAt) };
313
325
  if (input.title !== undefined && input.title !== row.title) {
314
326
  patch.title = input.title;
315
- patch.slug = await articleSlug(input.title, row.id);
327
+ patch.slug = await uniqueArticleSlug(input.title, row.id);
316
328
  }
317
329
  if (input.description !== undefined)
318
330
  patch.description = input.description;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/api-resource-article",
3
- "version": "1.2.7",
3
+ "version": "1.3.0",
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,7 +35,7 @@
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.1",
38
+ "@molecule/api-resource-follow": "1.1.2",
39
39
  "@molecule/api-resource-reaction": "1.0.8",
40
40
  "@molecule/api-slug": "1.0.3",
41
41
  "@types/express": "5.0.6",