@molecule/api-resource-comment 1.1.4 → 1.2.1

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-17T20:52:27.537Z
+Generated: 2026-10-20T08:23:35.474Z
 -->
 
 # @molecule/api-resource-comment
@@ -16,7 +16,8 @@ replies, pagination, and ownership-based authorization.
 **Tables this package owns: `comments` and `comment_numbers`.** A comment row is found by its
 `comments.id` (a UUID); `comment_numbers` gives it the sequential integer many clients address it
 by, and the join between the two is `comment_numbers.commentId` = `comments.id` (declared FK,
-`ON DELETE CASCADE`) — one row per numbered comment, never a mapping table of your own.
+`ON DELETE CASCADE`) — one row per comment created through this package, never a mapping table
+of your own.
 
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
@@ -227,7 +228,9 @@ function update(req: MoleculeRequest, res: MoleculeResponse): Promise<void>
 #### `numberComment(commentId)`
 
 The comment's number, allocating the next one when it has none. Numbers are
-unique and increase.
+unique and increase. Use it for a comment that was inserted into `comments`
+without `createComment()` — every comment created through this package is
+numbered already.
 
 ```typescript
 function numberComment(commentId: string): Promise<number>
@@ -241,6 +244,10 @@ function numberComment(commentId: string): Promise<number>
 
 Creates a comment and its number together: both are written, or neither.
 
+This is `createComment()` under the name an integer-id API reads best — it
+takes the same arguments and returns the same `NumberedComment`. Address the
+result by `number` and read it back with `getCommentByNumber(number)`.
+
 ```typescript
 function createNumberedComment(
   resourceType: string,
@@ -259,7 +266,9 @@ function createNumberedComment(
 
 #### `getCommentByNumber(number)`
 
-The comment a number belongs to.
+The comment a number belongs to — the lookup behind an integer-addressed
+route such as `DELETE /comments/:id`: find the comment here, then pass its
+`id` to `deleteComment()`/`updateComment()`.
 
 ```typescript
 function getCommentByNumber(number: number): Promise<NumberedComment | null>
@@ -272,7 +281,11 @@ function getCommentByNumber(number: number): Promise<NumberedComment | null>
 #### `commentNumbers(commentIds)`
 
 The numbers of the given comments, for listing them with their numbers.
-Comments without a number are left out of the map.
+
+Every comment created through this package is numbered, so a comment missing
+from the map was inserted directly into `comments` (or predates numbering by
+default); give it one with `numberComment(id)`. Never read a missing entry as
+`0` — `0` is not a comment id, and an integer id of `0` cannot be found again.
 
 ```typescript
 function commentNumbers(commentIds: readonly string[]): Promise<Map<string, number>>
@@ -284,7 +297,18 @@ function commentNumbers(commentIds: readonly string[]): Promise<Map<string, numb
 
 #### `createComment(resourceType, resourceId, userId, data)`
 
-Creates a new comment on a resource.
+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
+`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
+function.
+
+Both `__setup__` SQL files are required (`comments`, `comment_numbers`).
 
 ```typescript
 function createComment(
@@ -292,7 +316,7 @@ function createComment(
   resourceId: string,
   userId: string,
   data: CreateCommentInput,
-): Promise<Comment>
+): Promise<NumberedComment>
 ```
 
 - `resourceType` — The type of resource being commented on.
@@ -300,13 +324,17 @@ function createComment(
 - `userId` — The ID of the commenting user.
 - `data` — The comment creation input.
 
-**Returns:** The created comment.
+**Returns:** The created comment with its sequential `number`.
 
 #### `getCommentsByResource(resourceType, resourceId, options)`
 
 Retrieves paginated comments for a resource, ordered by creation date descending.
 Only returns top-level comments (no replies).
 
+The rows carry each comment's UUID `id`; for an API that addresses comments by an
+integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
+wrote is in that map, and a missing entry (a raw insert) is never `0`.
+
 ```typescript
 function getCommentsByResource(
   resourceType: string,
@@ -329,7 +357,7 @@ Retrieves a single comment by ID.
 function getCommentById(commentId: string): Promise<Comment | null>
 ```
 
-- `commentId` — The comment ID to look up.
+- `commentId` — The comment's UUID. For the sequential integer an integer-addressed API uses, call `getCommentByNumber(number)` instead.
 
 **Returns:** The comment or `null` if not found.
 
@@ -345,7 +373,7 @@ function updateComment(
 ): Promise<Comment | null>
 ```
 
-- `commentId` — The comment ID to update.
+- `commentId` — The comment's UUID. For an integer number, resolve it with `getCommentByNumber(number)` first.
 - `userId` — The requesting user's ID (must match comment owner).
 - `data` — The update input.
 
@@ -359,7 +387,7 @@ Deletes a comment. Only the comment owner can delete.
 function deleteComment(commentId: string, userId: string): Promise<boolean>
 ```
 
-- `commentId` — The comment ID to delete.
+- `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`.
 - `userId` — The requesting user's ID (must match comment owner).
 
 **Returns:** `true` if deleted, `false` if not found or unauthorized.
@@ -501,13 +529,17 @@ Peer dependencies:
 - **A scaffold that lists this package already has these tables** — its `__setup__` SQL is
   copied into the app at create time and replayed on every boot, so do not copy it into
   `api/migrations/` yourself; only a package added after the scaffold needs that.
-  `src/__setup__/comments.sql` ships with this package and must exist in the target
-  database before use (scaffolded apps apply it automatically; existing apps must apply it
-  first).
-- **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
-  UUID and give each comment a sequential number — `createNumberedComment()` creates both
-  in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
-  Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
+  Both SQL files this package ships — `src/__setup__/comments.sql` and
+  `src/__setup__/comment_numbers.sql` — must exist in the target database before use
+  (scaffolded apps apply both automatically; existing apps must apply both first).
+- **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
+  `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.
 - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
   with no auth middleware (comment threads on public content). If the
   commented resources are private in your app, add an authorizer that checks

package/dist/index.d.ts

@@ -7,7 +7,8 @@
  * **Tables this package owns: `comments` and `comment_numbers`.** A comment row is found by its
  * `comments.id` (a UUID); `comment_numbers` gives it the sequential integer many clients address it
  * by, and the join between the two is `comment_numbers.commentId` = `comments.id` (declared FK,
- * `ON DELETE CASCADE`) — one row per numbered comment, never a mapping table of your own.
+ * `ON DELETE CASCADE`) — one row per comment created through this package, never a mapping table
+ * of your own.
  *
  * @module
  * @example
@@ -33,13 +34,17 @@
  * - **A scaffold that lists this package already has these tables** — its `__setup__` SQL is
  *   copied into the app at create time and replayed on every boot, so do not copy it into
  *   `api/migrations/` yourself; only a package added after the scaffold needs that.
- *   `src/__setup__/comments.sql` ships with this package and must exist in the target
- *   database before use (scaffolded apps apply it automatically; existing apps must apply it
- *   first).
- * - **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
- *   UUID and give each comment a sequential number — `createNumberedComment()` creates both
- *   in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
- *   Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
+ *   Both SQL files this package ships — `src/__setup__/comments.sql` and
+ *   `src/__setup__/comment_numbers.sql` — must exist in the target database before use
+ *   (scaffolded apps apply both automatically; existing apps must apply both first).
+ * - **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
+ *   `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.
  * - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
  *   with no auth middleware (comment threads on public content). If the
  *   commented resources are private in your app, add an authorizer that checks

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/index.js

@@ -7,7 +7,8 @@
  * **Tables this package owns: `comments` and `comment_numbers`.** A comment row is found by its
  * `comments.id` (a UUID); `comment_numbers` gives it the sequential integer many clients address it
  * by, and the join between the two is `comment_numbers.commentId` = `comments.id` (declared FK,
- * `ON DELETE CASCADE`) — one row per numbered comment, never a mapping table of your own.
+ * `ON DELETE CASCADE`) — one row per comment created through this package, never a mapping table
+ * of your own.
  *
  * @module
  * @example
@@ -33,13 +34,17 @@
  * - **A scaffold that lists this package already has these tables** — its `__setup__` SQL is
  *   copied into the app at create time and replayed on every boot, so do not copy it into
  *   `api/migrations/` yourself; only a package added after the scaffold needs that.
- *   `src/__setup__/comments.sql` ships with this package and must exist in the target
- *   database before use (scaffolded apps apply it automatically; existing apps must apply it
- *   first).
- * - **Integer comment ids (RealWorld's `comment.id`, most public API specs):** keep the
- *   UUID and give each comment a sequential number — `createNumberedComment()` creates both
- *   in one transaction, `getCommentByNumber(n)` finds it, `commentNumbers(ids)` maps a list.
- *   Apply `src/__setup__/comment_numbers.sql` too. Never build your own id-mapping table.
+ *   Both SQL files this package ships — `src/__setup__/comments.sql` and
+ *   `src/__setup__/comment_numbers.sql` — must exist in the target database before use
+ *   (scaffolded apps apply both automatically; existing apps must apply both first).
+ * - **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
+ *   `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.
  * - **Reads are PUBLIC by default.** `list`, `read`, `replies`, and `count` ship
  *   with no auth middleware (comment threads on public content). If the
  *   commented resources are private in your app, add an authorizer that checks

package/dist/numbering.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Number allocation for comments — the `comment_numbers` rows behind
+ * `NumberedComment.number`.
+ *
+ * Internal to this package: `createComment()` calls `allocateCommentNumber()`
+ * so every comment it writes has a number, and `numbers.ts` re-exposes the
+ * public surface (`numberComment`, `commentNumbers`, …). The allocation needs
+ * no interactive transaction — the unique key on `number` is what makes a
+ * concurrent writer lose, and the next attempt reads the new highest number —
+ * so it also works on a database bond without transactions (Cloudflare D1).
+ *
+ * @module
+ */
+/**
+ * The comment's number, allocating the next one when it has none. Numbers are
+ * unique and increase. A concurrent writer that took the number first fails
+ * the insert on the unique key, and the next attempt reads the highest number
+ * again. Inside a caller's transaction the work runs once — a failed statement
+ * can poison it (Postgres) — and the caller decides.
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its sequential number.
+ * @throws {Error} When no number could be allocated after several attempts.
+ */
+export declare function allocateCommentNumber(commentId: string): Promise<number>;
+/**
+ * The numbers of the given comments, in one query.
+ *
+ * Every comment this package creates has a number, so a comment missing from
+ * the map was inserted into `comments` without `createComment()` (a raw insert,
+ * or a row from before this package numbered by default). Such a row has NO
+ * number — `numberComment(id)` gives it one. Never read a missing entry as `0`:
+ * `0` is not a comment id.
+ *
+ * @param commentIds - The comments' UUIDs.
+ * @returns Each numbered comment's UUID mapped to its number.
+ */
+export declare function numbersForComments(commentIds: readonly string[]): Promise<Map<string, number>>;
+//# sourceMappingURL=numbering.d.ts.map

package/dist/numbering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbering.d.ts","sourceRoot":"","sources":["../src/numbering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqCH;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAM9B"}

package/dist/numbering.js

@@ -0,0 +1,84 @@
+/**
+ * Number allocation for comments — the `comment_numbers` rows behind
+ * `NumberedComment.number`.
+ *
+ * Internal to this package: `createComment()` calls `allocateCommentNumber()`
+ * so every comment it writes has a number, and `numbers.ts` re-exposes the
+ * public surface (`numberComment`, `commentNumbers`, …). The allocation needs
+ * no interactive transaction — the unique key on `number` is what makes a
+ * concurrent writer lose, and the next attempt reads the new highest number —
+ * so it also works on a database bond without transactions (Cloudflare D1).
+ *
+ * @module
+ */
+import { create as dbCreate, findMany, findOne, getActiveTransaction } from '@molecule/api-database';
+/** The table the numbers live in. */
+const NUMBERS = 'comment_numbers';
+/** How many times allocation is redone when a concurrent writer took the number first. */
+const MAX_ATTEMPTS = 5;
+/**
+ * Allocates the next number for a comment that has none. Each call is one
+ * read and, when the comment is unnumbered, one insert.
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its number.
+ */
+async function allocate(commentId) {
+    const existing = await findOne(NUMBERS, [
+        { field: 'commentId', operator: '=', value: commentId },
+    ]);
+    if (existing)
+        return Number(existing.number);
+    const [last] = await findMany(NUMBERS, {
+        orderBy: [{ field: 'number', direction: 'desc' }],
+        limit: 1,
+    });
+    const number = (last ? Number(last.number) : 0) + 1;
+    await dbCreate(NUMBERS, { number, commentId });
+    return number;
+}
+/**
+ * The comment's number, allocating the next one when it has none. Numbers are
+ * unique and increase. A concurrent writer that took the number first fails
+ * the insert on the unique key, and the next attempt reads the highest number
+ * again. Inside a caller's transaction the work runs once — a failed statement
+ * can poison it (Postgres) — and the caller decides.
+ *
+ * @param commentId - The comment's UUID.
+ * @returns Its sequential number.
+ * @throws {Error} When no number could be allocated after several attempts.
+ */
+export async function allocateCommentNumber(commentId) {
+    if (getActiveTransaction())
+        return allocate(commentId);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await allocate(commentId);
+        }
+        catch (error) {
+            if (attempt >= MAX_ATTEMPTS) {
+                throw new Error(`Could not number comment ${commentId}`, { cause: error });
+            }
+        }
+    }
+}
+/**
+ * The numbers of the given comments, in one query.
+ *
+ * Every comment this package creates has a number, so a comment missing from
+ * the map was inserted into `comments` without `createComment()` (a raw insert,
+ * or a row from before this package numbered by default). Such a row has NO
+ * number — `numberComment(id)` gives it one. Never read a missing entry as `0`:
+ * `0` is not a comment id.
+ *
+ * @param commentIds - The comments' UUIDs.
+ * @returns Each numbered comment's UUID mapped to its number.
+ */
+export async function numbersForComments(commentIds) {
+    if (commentIds.length === 0)
+        return new Map();
+    const rows = await findMany(NUMBERS, {
+        where: [{ field: 'commentId', operator: 'in', value: [...commentIds] }],
+    });
+    return new Map(rows.map((r) => [r.commentId, Number(r.number)]));
+}

package/dist/numbers.d.ts

@@ -4,6 +4,13 @@
  * API specs). 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
+ * comment and its number together, so every comment this package creates is
+ * numbered, and a numbered API never has to remember a second call.
+ * `createNumberedComment()` is the same create, kept as the name that path
+ * reads best. `numberComment(id)` numbers a row that was inserted without it
+ * (a raw insert, or a row from before numbering was the default).
+ *
  * @module
  */
 import type { Comment, CreateCommentInput } from './types.js';
@@ -14,7 +21,9 @@ export type NumberedComment = Comment & {
 };
 /**
  * The comment's number, allocating the next one when it has none. Numbers are
- * unique and increase.
+ * unique and increase. Use it for a comment that was inserted into `comments`
+ * without `createComment()` — every comment created through this package is
+ * numbered already.
  *
  * @param commentId - The comment's UUID.
  * @returns Its sequential number.
@@ -24,6 +33,10 @@ export declare function numberComment(commentId: string): Promise<number>;
 /**
  * Creates a comment and its number together: both are written, or neither.
  *
+ * This is `createComment()` under the name an integer-id API reads best — it
+ * takes the same arguments and returns the same `NumberedComment`. Address the
+ * result by `number` and read it back with `getCommentByNumber(number)`.
+ *
  * @param resourceType - The type of resource being commented on.
  * @param resourceId - The ID of the resource being commented on.
  * @param userId - The ID of the commenting user.
@@ -32,7 +45,9 @@ export declare function numberComment(commentId: string): Promise<number>;
  */
 export declare function createNumberedComment(resourceType: string, resourceId: string, userId: string, data: CreateCommentInput): Promise<NumberedComment>;
 /**
- * The comment a number belongs to.
+ * The comment a number belongs to — the lookup behind an integer-addressed
+ * route such as `DELETE /comments/:id`: find the comment here, then pass its
+ * `id` to `deleteComment()`/`updateComment()`.
  *
  * @param number - The comment's sequential number.
  * @returns The comment with its number, or `null` when no comment has it.
@@ -40,7 +55,11 @@ export declare function createNumberedComment(resourceType: string, resourceId:
 export declare function getCommentByNumber(number: number): Promise<NumberedComment | null>;
 /**
  * The numbers of the given comments, for listing them with their numbers.
- * Comments without a number are left out of the map.
+ *
+ * Every comment created through this package is numbered, so a comment missing
+ * from the map was inserted directly into `comments` (or predates numbering by
+ * default); give it one with `numberComment(id)`. Never read a missing entry as
+ * `0` — `0` is not a comment id, and an integer id of `0` cannot be found again.
  *
  * @param commentIds - The comments' UUIDs.
  * @returns Each numbered comment's UUID mapped to its number.

package/dist/numbers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAI7D,qDAAqD;AACrD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IACtC,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAuDD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQxF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMhG"}
+{"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"}

package/dist/numbers.js

@@ -4,73 +4,40 @@
  * API specs). 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
+ * comment and its number together, so every comment this package creates is
+ * numbered, and a numbered API never has to remember a second call.
+ * `createNumberedComment()` is the same create, kept as the name that path
+ * reads best. `numberComment(id)` numbers a row that was inserted without it
+ * (a raw insert, or a row from before numbering was the default).
+ *
  * @module
  */
-import { create as dbCreate, findMany, findOne, getActiveTransaction, withTransaction, } from '@molecule/api-database';
+import { findOne } from '@molecule/api-database';
+import { allocateCommentNumber, numbersForComments } from './numbering.js';
 import { createComment, getCommentById } from './service.js';
+/** The table the numbers live in. */
 const NUMBERS = 'comment_numbers';
-/** How many times the work is redone when a concurrent writer took the number first. */
-const MAX_ATTEMPTS = 5;
-/**
- * Runs `work` in its own transaction, again when it fails: a concurrent
- * writer that took the same number fails the unique key, and the next
- * attempt allocates the next number. Inside a caller's transaction a failed
- * statement can poison it (Postgres), so there the work runs once and the
- * caller decides.
- *
- * @param what - What is being numbered, for the error.
- * @param work - The allocation.
- * @returns What `work` resolves to.
- */
-async function withNumberRetry(what, work) {
-    if (getActiveTransaction())
-        return work();
-    for (let attempt = 1;; attempt++) {
-        try {
-            return await withTransaction(work);
-        }
-        catch (error) {
-            if (attempt >= MAX_ATTEMPTS)
-                throw new Error(`Could not number ${what}`, { cause: error });
-            // Rolled back; a concurrent writer most likely took the number (its
-            // unique key failed). The next attempt reads the new highest number.
-        }
-    }
-}
-/**
- * Allocates the next number for a comment that has none (no transaction of its own).
- *
- * @param commentId - The comment's UUID.
- * @returns Its number.
- */
-async function allocate(commentId) {
-    const existing = await findOne(NUMBERS, [
-        { field: 'commentId', operator: '=', value: commentId },
-    ]);
-    if (existing)
-        return Number(existing.number);
-    const [last] = await findMany(NUMBERS, {
-        orderBy: [{ field: 'number', direction: 'desc' }],
-        limit: 1,
-    });
-    const number = (last ? Number(last.number) : 0) + 1;
-    await dbCreate(NUMBERS, { number, commentId });
-    return number;
-}
 /**
  * The comment's number, allocating the next one when it has none. Numbers are
- * unique and increase.
+ * unique and increase. Use it for a comment that was inserted into `comments`
+ * without `createComment()` — every comment created through this package is
+ * numbered already.
  *
  * @param commentId - The comment's UUID.
  * @returns Its sequential number.
  * @throws {Error} When no number could be allocated after several attempts.
  */
 export async function numberComment(commentId) {
-    return withNumberRetry(`comment ${commentId}`, () => allocate(commentId));
+    return allocateCommentNumber(commentId);
 }
 /**
  * Creates a comment and its number together: both are written, or neither.
  *
+ * This is `createComment()` under the name an integer-id API reads best — it
+ * takes the same arguments and returns the same `NumberedComment`. Address the
+ * result by `number` and read it back with `getCommentByNumber(number)`.
+ *
  * @param resourceType - The type of resource being commented on.
  * @param resourceId - The ID of the resource being commented on.
  * @param userId - The ID of the commenting user.
@@ -78,13 +45,12 @@ export async function numberComment(commentId) {
  * @returns The created comment with its number.
  */
 export async function createNumberedComment(resourceType, resourceId, userId, data) {
-    return withNumberRetry('a new comment', async () => {
-        const comment = await createComment(resourceType, resourceId, userId, data);
-        return { ...comment, number: await allocate(comment.id) };
-    });
+    return createComment(resourceType, resourceId, userId, data);
 }
 /**
- * The comment a number belongs to.
+ * The comment a number belongs to — the lookup behind an integer-addressed
+ * route such as `DELETE /comments/:id`: find the comment here, then pass its
+ * `id` to `deleteComment()`/`updateComment()`.
  *
  * @param number - The comment's sequential number.
  * @returns The comment with its number, or `null` when no comment has it.
@@ -102,16 +68,15 @@ export async function getCommentByNumber(number) {
 }
 /**
  * The numbers of the given comments, for listing them with their numbers.
- * Comments without a number are left out of the map.
+ *
+ * Every comment created through this package is numbered, so a comment missing
+ * from the map was inserted directly into `comments` (or predates numbering by
+ * default); give it one with `numberComment(id)`. Never read a missing entry as
+ * `0` — `0` is not a comment id, and an integer id of `0` cannot be found again.
  *
  * @param commentIds - The comments' UUIDs.
  * @returns Each numbered comment's UUID mapped to its number.
  */
 export async function commentNumbers(commentIds) {
-    if (commentIds.length === 0)
-        return new Map();
-    const rows = await findMany(NUMBERS, {
-        where: [{ field: 'commentId', operator: 'in', value: [...commentIds] }],
-    });
-    return new Map(rows.map((r) => [r.commentId, Number(r.number)]));
+    return numbersForComments(commentIds);
 }

package/dist/service.d.ts

@@ -6,21 +6,39 @@
  *
  * @module
  */
+import type { NumberedComment } from './numbers.js';
 import type { Comment, CreateCommentInput, PaginatedResult, PaginationOptions, UpdateCommentInput } from './types.js';
 /**
- * Creates a new comment on a resource.
+ * 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
+ * `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
+ * function.
+ *
+ * Both `__setup__` SQL files are required (`comments`, `comment_numbers`).
  *
  * @param resourceType - The type of resource being commented on.
  * @param resourceId - The ID of the resource being commented on.
  * @param userId - The ID of the commenting user.
  * @param data - The comment creation input.
- * @returns The created comment.
+ * @returns The created comment with its sequential `number`.
+ * @throws {Error} When the comment could not be numbered; the comment row is
+ *   removed again so the caller is not told a create failed while it exists.
  */
-export declare function createComment(resourceType: string, resourceId: string, userId: string, data: CreateCommentInput): Promise<Comment>;
+export declare function createComment(resourceType: string, resourceId: string, userId: string, data: CreateCommentInput): Promise<NumberedComment>;
 /**
  * Retrieves paginated comments for a resource, ordered by creation date descending.
  * Only returns top-level comments (no replies).
  *
+ * The rows carry each comment's UUID `id`; for an API that addresses comments by an
+ * integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
+ * wrote is in that map, and a missing entry (a raw insert) is never `0`.
+ *
  * @param resourceType - The type of resource.
  * @param resourceId - The ID of the resource.
  * @param options - Pagination options.
@@ -30,14 +48,16 @@ export declare function getCommentsByResource(resourceType: string, resourceId:
 /**
  * Retrieves a single comment by ID.
  *
- * @param commentId - The comment ID to look up.
+ * @param commentId - The comment's UUID. For the sequential integer an
+ *   integer-addressed API uses, call `getCommentByNumber(number)` instead.
  * @returns The comment or `null` if not found.
  */
 export declare function getCommentById(commentId: string): Promise<Comment | null>;
 /**
  * Updates a comment. Only the comment owner can update.
  *
- * @param commentId - The comment ID to update.
+ * @param commentId - The comment's UUID. For an integer number, resolve it with
+ *   `getCommentByNumber(number)` first.
  * @param userId - The requesting user's ID (must match comment owner).
  * @param data - The update input.
  * @returns The updated comment or `null` if not found or unauthorized.
@@ -46,7 +66,9 @@ export declare function updateComment(commentId: string, userId: string, data: U
 /**
  * Deletes a comment. Only the comment owner can delete.
  *
- * @param commentId - The comment ID to 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
+ *   `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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAInB;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAqBnC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAczB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAiBnC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/F"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAInB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAqBnC;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAE/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAczB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAiBnC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/F"}

package/dist/service.js

@@ -7,15 +7,29 @@
  * @module
  */
 import { count, create as dbCreate, deleteById, findById, findMany, updateById, } from '@molecule/api-database';
+import { allocateCommentNumber } from './numbering.js';
 const TABLE = 'comments';
 /**
- * Creates a new comment on a resource.
+ * 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
+ * `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
+ * function.
+ *
+ * Both `__setup__` SQL files are required (`comments`, `comment_numbers`).
  *
  * @param resourceType - The type of resource being commented on.
  * @param resourceId - The ID of the resource being commented on.
  * @param userId - The ID of the commenting user.
  * @param data - The comment creation input.
- * @returns The created comment.
+ * @returns The created comment with its sequential `number`.
+ * @throws {Error} When the comment could not be numbered; the comment row is
+ *   removed again so the caller is not told a create failed while it exists.
  */
 export async function createComment(resourceType, resourceId, userId, data) {
     const result = await dbCreate(TABLE, {
@@ -26,12 +40,29 @@ export async function createComment(resourceType, resourceId, userId, data) {
         body: data.body,
         editedAt: null,
     });
-    return result.data;
+    const comment = result.data;
+    try {
+        return { ...comment, number: await allocateCommentNumber(comment.id) };
+    }
+    catch (error) {
+        // The caller is told the create failed, so the row must not stay behind.
+        try {
+            await deleteById(TABLE, comment.id);
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], `Could not number comment ${comment.id}, and could not remove the unnumbered row`, { cause: cleanupError });
+        }
+        throw error;
+    }
 }
 /**
  * Retrieves paginated comments for a resource, ordered by creation date descending.
  * Only returns top-level comments (no replies).
  *
+ * The rows carry each comment's UUID `id`; for an API that addresses comments by an
+ * integer, map a page's ids with `commentNumbers()` — every comment `createComment()`
+ * wrote is in that map, and a missing entry (a raw insert) is never `0`.
+ *
  * @param resourceType - The type of resource.
  * @param resourceId - The ID of the resource.
  * @param options - Pagination options.
@@ -59,7 +90,8 @@ export async function getCommentsByResource(resourceType, resourceId, options =
 /**
  * Retrieves a single comment by ID.
  *
- * @param commentId - The comment ID to look up.
+ * @param commentId - The comment's UUID. For the sequential integer an
+ *   integer-addressed API uses, call `getCommentByNumber(number)` instead.
  * @returns The comment or `null` if not found.
  */
 export async function getCommentById(commentId) {
@@ -68,7 +100,8 @@ export async function getCommentById(commentId) {
 /**
  * Updates a comment. Only the comment owner can update.
  *
- * @param commentId - The comment ID to update.
+ * @param commentId - The comment's UUID. For an integer number, resolve it with
+ *   `getCommentByNumber(number)` first.
  * @param userId - The requesting user's ID (must match comment owner).
  * @param data - The update input.
  * @returns The updated comment or `null` if not found or unauthorized.
@@ -89,7 +122,9 @@ export async function updateComment(commentId, userId, data) {
 /**
  * Deletes a comment. Only the comment owner can delete.
  *
- * @param commentId - The comment ID to 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
+ *   `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.1.4",
+  "version": "1.2.1",
   "description": "Threaded comments on any resource with polymorphic attachment and pagination",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@molecule/api-database": "1.1.3",
-    "@molecule/api-database-sqlite": "1.2.6",
+    "@molecule/api-database-sqlite": "1.3.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11",

package/src/__setup__/comment_numbers.sql

@@ -1,7 +1,8 @@
 -- Sequential integer numbers for comments, for APIs whose clients address a
--- comment by an integer id (RealWorld's `comment.id` is an integer). Opt-in:
--- written by numberComment() / createNumberedComment(); comments without a
--- number keep working by their UUID.
+-- comment by an integer id (RealWorld's `comment.id` is an integer).
+-- 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.
 CREATE TABLE IF NOT EXISTS "comment_numbers" (
   "number" INTEGER PRIMARY KEY,
   "commentId" UUID NOT NULL UNIQUE REFERENCES "comments"("id") ON DELETE CASCADE