Per-resource comments for Basalt: threads (nested replies), @mentions, and resolve/reopen, isolated by tenant, emitting events that connect to @basaltkit/realtime (live discussion) and @basaltkit/notifications (notify who was mentioned). You need this module when you want collaboration — commenting on a note, a project, a task.
A comment system involves more than storing text: threads with replies, extracting @mentions to notify, marking a discussion as resolved, and restricting edits to the author. This module gives you all of that — attached to any resource (resourceType:resourceId) and isolated by tenant — and emits events for the rest of the ecosystem to react to.
Depends on @basaltkit/core and @basaltkit/http (3.x; routes served by any adapter). No database required: the default store is in-memory (CommentStore contract for production).
commentRoutes() (all require login; author comes from ctx().user):
Route
Description
GET /comments?resourceType=&resourceId=
Comment tree for the resource.
POST /comments{ resourceType, resourceId, body, parentId?, anchor? }
Create (or reply). parentId must be a comment of the same resource, otherwise 400 COMMENT_PARENT_NOT_FOUND. anchor is a JSON object (≤ 4 KB).
PATCH /comments/:id{ body }
Edit — author only.
DELETE /comments/:id
Delete — author only.
POST /comments/:id/resolve · /reopen
Resolve / reopen the discussion — author only.
Pass commentRoutes({ authorize: (action, { resourceType, resourceId, comment? }, user) => boolean }) to apply your own per-resource policy (it replaces the default; compose with defaultCommentPolicy). Throw CommentNotFoundError from it to answer 404 instead of 403. commentRoutes({ meta }) merges extra route meta (e.g. { can: 'comments:write' }) into every route; auth: true is always kept.
Registers the COMMENTS token. mentionPattern is a g regex whose first group is the mentioned id (default DEFAULT_MENTION_PATTERN: @id not preceded by a word character, ., + or -, so an email's domain is not a mention; DELIMITED_MENTION_PATTERN reads @{id}). Bodies are capped at maxBodyLength characters (default 10 000) and maxMentions distinct mentions (default 50); resolveMentions(ids, tenantId) keeps only the ids that may be mentioned (e.g. tenant members) — throw from it to reject the comment instead.
Opt-in: deletion: 'soft' keeps removed comments as tombstones (deletedAt/deletedBy/deleteReason; list()/tree() blank the body and mentions); editWindowMs refuses edits after the window (CommentEditWindowClosedError, 409); revisions: true records each previous body (needs a store with addRevision/revisions, otherwise boot fails with CommentRevisionsUnsupportedError).
Without tenantId, uses ctx().tenant.id (otherwise CommentTenantRequiredError). Inside a tenant context an explicit tenantId must equal it (CommentTenantMismatchError, 403). An app without @basaltkit/tenancy has no tenant dimension: its comments are keyed by SINGLE_TENANT_SCOPE ('@single', a sentinel outside the tenant-id grammar; a tenant carrying it is refused with CommentTenantReservedError, COMMENT_TENANT_RESERVED, 400).
> Upgrading from 3.x (single-tenant data): the key used to be 'default', a valid tenant id — a tenant named default could read, edit and delete the single-tenant comments. Re-key persisted rows once: UPDATE comments SET "tenantId" = '@single' WHERE "tenantId" = 'default' (@basaltkit/comments-prisma; with @basaltkit/comments-sqlite the column is tenant_id). Skip it if default was ever a real tenant in that database.
comment:created · comment:updated · comment:deleted · comment:resolved · comment:reopened · comment:mentioned (one per mentioned user). Every payload carries actorId when an actor is known (the author, the resolver, the explicit actor, or ctx().user.id).
Package reference
Mirrors the package README (single source). Install
@basaltkit/commentsv4.1.1— npm · source.<p align="center"> <a href="https://basaltkit-docs.pages.dev"> <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440"> </a> </p>
@basaltkit/comments
Per-resource comments for Basalt: threads (nested replies), @mentions, and resolve/reopen, isolated by tenant, emitting events that connect to
@basaltkit/realtime(live discussion) and@basaltkit/notifications(notify who was mentioned). You need this module when you want collaboration — commenting on a note, a project, a task.What this module solves
A comment system involves more than storing text: threads with replies, extracting @mentions to notify, marking a discussion as resolved, and restricting edits to the author. This module gives you all of that — attached to any resource (
resourceType:resourceId) and isolated by tenant — and emits events for the rest of the ecosystem to react to.Installation
Depends on
@basaltkit/coreand@basaltkit/http(3.x; routes served by any adapter). No database required: the default store is in-memory (CommentStorecontract for production).Get started in 5 minutes
addextracts @mentions from the body (default@id), stores them on the comment, and emitscomment:mentionedfor each mentioned user.Connecting to realtime and notifications
The power is in the events. Push comments live and notify mentioned users without coupling anything:
Routes
commentRoutes()(all require login; author comes fromctx().user):GET /comments?resourceType=&resourceId=POST /comments{ resourceType, resourceId, body, parentId?, anchor? }parentIdmust be a comment of the same resource, otherwise 400COMMENT_PARENT_NOT_FOUND.anchoris a JSON object (≤ 4 KB).PATCH /comments/:id{ body }DELETE /comments/:idPOST /comments/:id/resolve·/reopenPass
commentRoutes({ authorize: (action, { resourceType, resourceId, comment? }, user) => boolean })to apply your own per-resource policy (it replaces the default; compose withdefaultCommentPolicy). ThrowCommentNotFoundErrorfrom it to answer 404 instead of 403.commentRoutes({ meta })merges extra route meta (e.g.{ can: 'comments:write' }) into every route;auth: trueis always kept.API reference
commentsPlugin({ store?, mentionPattern?, maxBodyLength?, maxMentions?, resolveMentions?, deletion?, editWindowMs?, revisions? })Registers the
COMMENTStoken.mentionPatternis agregex whose first group is the mentioned id (defaultDEFAULT_MENTION_PATTERN:@idnot preceded by a word character,.,+or-, so an email's domain is not a mention;DELIMITED_MENTION_PATTERNreads@{id}). Bodies are capped atmaxBodyLengthcharacters (default 10 000) andmaxMentionsdistinct mentions (default 50);resolveMentions(ids, tenantId)keeps only the ids that may be mentioned (e.g. tenant members) — throw from it to reject the comment instead.Opt-in:
deletion: 'soft'keeps removed comments as tombstones (deletedAt/deletedBy/deleteReason;list()/tree()blank the body and mentions);editWindowMsrefuses edits after the window (CommentEditWindowClosedError, 409);revisions: truerecords each previous body (needs a store withaddRevision/revisions, otherwise boot fails withCommentRevisionsUnsupportedError).class Commentson(resourceType, resourceId, tenantId?){ add, list, tree }for a resource.get(id, tenantId?)edit(id, body, tenantId? | { tenantId?, actorId? })comment:updated. 404 on a soft-deleted comment, 409 pasteditWindowMs.remove(id, tenantId? | { tenantId?, actorId?, by?, reason? })comment:deleted(soft: truefor a tombstone).resolve(id, by, tenantId?)·reopen(id, tenantId? | { tenantId?, actorId? })comment:resolved/comment:reopened.revisions(id, tenantId?)revisions: true).Without
tenantId, usesctx().tenant.id(otherwiseCommentTenantRequiredError). Inside a tenant context an explicittenantIdmust equal it (CommentTenantMismatchError, 403). An app without@basaltkit/tenancyhas no tenant dimension: its comments are keyed bySINGLE_TENANT_SCOPE('@single', a sentinel outside the tenant-id grammar; a tenant carrying it is refused withCommentTenantReservedError,COMMENT_TENANT_RESERVED, 400).> Upgrading from 3.x (single-tenant data): the key used to be
'default', a valid tenant id — a tenant nameddefaultcould read, edit and delete the single-tenant comments. Re-key persisted rows once:UPDATE comments SET "tenantId" = '@single' WHERE "tenantId" = 'default'(@basaltkit/comments-prisma; with@basaltkit/comments-sqlitethe column istenant_id). Skip it ifdefaultwas ever a real tenant in that database.Events
comment:created·comment:updated·comment:deleted·comment:resolved·comment:reopened·comment:mentioned(one per mentioned user). Every payload carriesactorIdwhen an actor is known (the author, the resolver, the explicit actor, orctx().user.id).How it connects to other modules
@basaltkit/realtime— pushescomment:createdto the resource's channel (live discussion).@basaltkit/notifications— reacts tocomment:mentionedto notify mentioned users.@basaltkit/auth/@basaltkit/tenancy— provide the user (author) and tenant from context.