@molecule/api-resource-comment 1.2.1 → 1.2.3

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-20T08:23:35.474Z
+Generated: 2026-10-31T12:45:29.246Z
 -->
 
 # @molecule/api-resource-comment
@@ -301,8 +301,8 @@ Creates a new comment on a resource, with its sequential number.
 
 The comment row and its `comment_numbers` row are written together: the
 returned comment carries `number` (1, 2, 3, …) beside its UUID `id`. An API
-whose clients address a comment by an integer (RealWorld's `comment.id`,
-`DELETE /comments/:id`) returns `number` as that id and reads it back with
+whose clients address a comment by a stable integer
+returns `number` as that id and reads it back with
 `getCommentByNumber(number)` — never hand-build an id from the UUID.
 `createNumberedComment()` is this same create under the name that path reads
 best; `numberComment(id)` numbers a row that was inserted without this
@@ -387,7 +387,7 @@ Deletes a comment. Only the comment owner can delete.
 function deleteComment(commentId: string, userId: string): Promise<boolean>
 ```
 
-- `commentId` — The comment's UUID. To delete by the integer number an API like RealWorld exposes (`DELETE /comments/:id`), look the row up with `getCommentByNumber(number)` and pass its `id`.
+- `commentId` — The comment's UUID. To delete by the integer number an API exposes, look the row up with `getCommentByNumber(number)` and pass its `id`.
 - `userId` — The requesting user's ID (must match comment owner).
 
 **Returns:** `true` if deleted, `false` if not found or unauthorized.
@@ -535,8 +535,8 @@ Peer dependencies:
 - **Integer comment ids — every comment is numbered by default.** `createComment()`
   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
   `createNumberedComment()` is the same create under the name an integer-id API reads best.
-  For an API whose clients address a comment by an integer (RealWorld's `comment.id`,
-  `DELETE /comments/:id`), return `number` as the id and read it back with
+  For an API whose clients address a comment by a stable integer,
+  return `number` as the id and read it back with
   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing
   `commentNumbers(ids)` entry as `0` (a row inserted without `createComment()` has no number;
   `numberComment(id)` gives it one). Never build your own id-mapping table.
@@ -552,6 +552,15 @@ Peer dependencies:
   `resourceType`/`resourceId`): validate that the target exists in your domain
   code if orphaned threads matter, and reuse the same canonical type slugs as
   your other polymorphic resources (bookmarks, activity feed).
+- **Client: address the thread with an identifier the page already has, not with the
+  loaded parent.** List and post with `/:resourceType/:resourceId/comments`, using the
+  parent identifier from the route when it is the one this API expects; when the route
+  carries something else (a slug where the API needs an id), resolve the id first and keep
+  the comment controls visibly disabled until it is known. Edit and delete a comment by its
+  own id (`PUT`/`DELETE /comments/:commentId`). A submit handler that starts with
+  `if (!parent) return` does nothing when the user submits before the parent finishes
+  loading: no request, no error, the text still in the box. Never let a click silently do
+  nothing.
 
 ## E2E Tests
 

package/dist/index.d.ts

@@ -40,8 +40,8 @@
  * - **Integer comment ids — every comment is numbered by default.** `createComment()`
  *   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
  *   `createNumberedComment()` is the same create under the name an integer-id API reads best.
- *   For an API whose clients address a comment by an integer (RealWorld's `comment.id`,
- *   `DELETE /comments/:id`), return `number` as the id and read it back with
+ *   For an API whose clients address a comment by a stable integer,
+ *   return `number` as the id and read it back with
  *   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing
  *   `commentNumbers(ids)` entry as `0` (a row inserted without `createComment()` has no number;
  *   `numberComment(id)` gives it one). Never build your own id-mapping table.
@@ -57,6 +57,15 @@
  *   `resourceType`/`resourceId`): validate that the target exists in your domain
  *   code if orphaned threads matter, and reuse the same canonical type slugs as
  *   your other polymorphic resources (bookmarks, activity feed).
+ * - **Client: address the thread with an identifier the page already has, not with the
+ *   loaded parent.** List and post with `/:resourceType/:resourceId/comments`, using the
+ *   parent identifier from the route when it is the one this API expects; when the route
+ *   carries something else (a slug where the API needs an id), resolve the id first and keep
+ *   the comment controls visibly disabled until it is known. Edit and delete a comment by its
+ *   own id (`PUT`/`DELETE /comments/:commentId`). A submit handler that starts with
+ *   `if (!parent) return` does nothing when the user submits before the parent finishes
+ *   loading: no request, no error, the text still in the box. Never let a click silently do
+ *   nothing.
  *
  * @e2e
  * Integration checklist — drive the real UI (live preview, no mocks), adapt

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,cAAc,CAAA;AAC5B,cAAc,wBAAwB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -40,8 +40,8 @@
  * - **Integer comment ids — every comment is numbered by default.** `createComment()`
  *   writes the comment and its sequential `number` (1, 2, 3, …) together and returns both;
  *   `createNumberedComment()` is the same create under the name an integer-id API reads best.
- *   For an API whose clients address a comment by an integer (RealWorld's `comment.id`,
- *   `DELETE /comments/:id`), return `number` as the id and read it back with
+ *   For an API whose clients address a comment by a stable integer,
+ *   return `number` as the id and read it back with
  *   `getCommentByNumber(n)` — never hand-build an id from the UUID, and never read a missing
  *   `commentNumbers(ids)` entry as `0` (a row inserted without `createComment()` has no number;
  *   `numberComment(id)` gives it one). Never build your own id-mapping table.
@@ -57,6 +57,15 @@
  *   `resourceType`/`resourceId`): validate that the target exists in your domain
  *   code if orphaned threads matter, and reuse the same canonical type slugs as
  *   your other polymorphic resources (bookmarks, activity feed).
+ * - **Client: address the thread with an identifier the page already has, not with the
+ *   loaded parent.** List and post with `/:resourceType/:resourceId/comments`, using the
+ *   parent identifier from the route when it is the one this API expects; when the route
+ *   carries something else (a slug where the API needs an id), resolve the id first and keep
+ *   the comment controls visibly disabled until it is known. Edit and delete a comment by its
+ *   own id (`PUT`/`DELETE /comments/:commentId`). A submit handler that starts with
+ *   `if (!parent) return` does nothing when the user submits before the parent finishes
+ *   loading: no request, no error, the text still in the box. Never let a click silently do
+ *   nothing.
  *
  * @e2e
  * Integration checklist — drive the real UI (live preview, no mocks), adapt

package/dist/numbers.d.ts

@@ -1,7 +1,6 @@
 /**
  * Sequential integer numbers for comments, for APIs whose clients address a
- * comment by an integer (RealWorld's `comment.id` is one; so are most public
- * API specs). The comment keeps its UUID; the number lives in
+ * comment by an integer. The comment keeps its UUID; the number lives in
  * `comment_numbers` and is allocated once, at most one per comment.
  *
  * **Numbering is the default create path:** `createComment()` writes the

package/dist/numbers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAK7D,qDAAqD;AACrD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IACtC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAQD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQxF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEhG"}
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAK7D,qDAAqD;AACrD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IACtC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAQD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQxF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAEhG"}

package/dist/numbers.js

@@ -1,7 +1,6 @@
 /**
  * Sequential integer numbers for comments, for APIs whose clients address a
- * comment by an integer (RealWorld's `comment.id` is one; so are most public
- * API specs). The comment keeps its UUID; the number lives in
+ * comment by an integer. The comment keeps its UUID; the number lives in
  * `comment_numbers` and is allocated once, at most one per comment.
  *
  * **Numbering is the default create path:** `createComment()` writes the

package/dist/service.d.ts

@@ -13,8 +13,8 @@ import type { Comment, CreateCommentInput, PaginatedResult, PaginationOptions, U
  *
  * The comment row and its `comment_numbers` row are written together: the
  * returned comment carries `number` (1, 2, 3, …) beside its UUID `id`. An API
- * whose clients address a comment by an integer (RealWorld's `comment.id`,
- * `DELETE /comments/:id`) returns `number` as that id and reads it back with
+ * whose clients address a comment by a stable integer
+ * returns `number` as that id and reads it back with
  * `getCommentByNumber(number)` — never hand-build an id from the UUID.
  * `createNumberedComment()` is this same create under the name that path reads
  * best; `numberComment(id)` numbers a row that was inserted without this
@@ -67,7 +67,7 @@ export declare function updateComment(commentId: string, userId: string, data: U
  * Deletes a comment. Only the comment owner can delete.
  *
  * @param commentId - The comment's UUID. To delete by the integer number an
- *   API like RealWorld exposes (`DELETE /comments/:id`), look the row up with
+ *   API exposes, look the row up with
  *   `getCommentByNumber(number)` and pass its `id`.
  * @param userId - The requesting user's ID (must match comment owner).
  * @returns `true` if deleted, `false` if not found or unauthorized.

package/dist/service.js

@@ -14,8 +14,8 @@ const TABLE = 'comments';
  *
  * The comment row and its `comment_numbers` row are written together: the
  * returned comment carries `number` (1, 2, 3, …) beside its UUID `id`. An API
- * whose clients address a comment by an integer (RealWorld's `comment.id`,
- * `DELETE /comments/:id`) returns `number` as that id and reads it back with
+ * whose clients address a comment by a stable integer
+ * returns `number` as that id and reads it back with
  * `getCommentByNumber(number)` — never hand-build an id from the UUID.
  * `createNumberedComment()` is this same create under the name that path reads
  * best; `numberComment(id)` numbers a row that was inserted without this
@@ -123,7 +123,7 @@ export async function updateComment(commentId, userId, data) {
  * Deletes a comment. Only the comment owner can delete.
  *
  * @param commentId - The comment's UUID. To delete by the integer number an
- *   API like RealWorld exposes (`DELETE /comments/:id`), look the row up with
+ *   API exposes, look the row up with
  *   `getCommentByNumber(number)` and pass its `id`.
  * @param userId - The requesting user's ID (must match comment owner).
  * @returns `true` if deleted, `false` if not found or unauthorized.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource-comment",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Threaded comments on any resource with polymorphic attachment and pagination",
   "type": "module",
   "main": "dist/index.js",
@@ -29,12 +29,12 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@molecule/api-database": "1.1.3",
-    "@molecule/api-database-sqlite": "1.3.0",
-    "@types/node": "26.1.2",
+    "@molecule/api-database": "1.2.2",
+    "@molecule/api-database-sqlite": "1.4.2",
+    "@types/node": "26.6.5",
     "typescript": "6.0.3",
-    "vitest": "4.1.11",
-    "zod": "4.4.3"
+    "vitest": "4.1.12",
+    "zod": "4.6.7"
   },
   "peerDependencies": {
     "@molecule/api-database": "^1.1.0",

package/src/__setup__/comment_numbers.sql

@@ -1,5 +1,5 @@
 -- Sequential integer numbers for comments, for APIs whose clients address a
--- comment by an integer id (RealWorld's `comment.id` is an integer).
+-- comment by an integer id instead of its internal UUID.
 -- createComment() / createNumberedComment() write this row with the comment;
 -- numberComment(id) numbers a row that was inserted without them. The comment
 -- keeps its UUID either way.