@happyvertical/smrt-tags

Hierarchical tagging with context-scoped slugs, multi-language aliases, and slug utilities.

Installation

pnpm add @happyvertical/smrt-tags

Usage

import { Tag, TagCollection, TagAlias, TagAliasCollection } from '@happyvertical/smrt-tags';
import { sanitizeSlug, validateSlug, generateUniqueSlug } from '@happyvertical/smrt-tags';

// Create a tag hierarchy
const collection = await TagCollection.create();

// `collection.create(...)` returns the saved row, so use it directly
// instead of `new Tag()` + a separate `.create(...)` step. The returned
// instance has its persisted `id` set for use as a parent reference.
const tech = await collection.create({
  slug: 'technology',
  name: 'Technology',
  context: 'blog', // defaults to 'global' if omitted
});

// Children reference their parent by UUID (`parentId`). With `tech`
// already saved, pass `tech.id` directly. `level` is recalculated by
// `TagCollection.moveTag` / `mergeTag` for later moves; you can pass it
// explicitly on create or let it stay at 0 and call moveTag later.
const ai = await collection.create({
  slug: 'artificial-intelligence',
  name: 'Artificial Intelligence',
  context: 'blog',
  parentId: tech.id,
  level: 1,
});

// Traverse hierarchy
const children = await tech.getChildren();
const ancestors = await ai.getAncestors();

// Context scoping -- same slug, different contexts
const blogNews = new Tag({ slug: 'news', name: 'News', context: 'blog' });
const forumNews = new Tag({ slug: 'news', name: 'Forum News', context: 'forum' });

// Multi-language aliases
const aliasCollection = await TagAliasCollection.create();
const alias = new TagAlias({
  tagSlug: 'technology',
  alias: 'Tecnologia',
  language: 'es',
  context: 'blog',
});
await aliasCollection.create(alias);

// Collection operations. Slug args resolve through (slug, context) —
// pass an explicit context when the same slug exists in multiple
// contexts, otherwise the resolver throws on ambiguity.
await collection.moveTag('artificial-intelligence', 'technology', 'blog'); // cycle-checked
await collection.mergeTag('source', 'target', 'blog');                     // moves children + aliases, deletes source
await collection.cleanupUnused();                                          // deletes tags with no children and no aliases

// Slug utilities
sanitizeSlug('My Cool Tag!');   // 'my-cool-tag'
validateSlug('my-tag-123');     // true

API

Models (SmrtObject)

Export	Description
Tag	Identified by slug + context. Hierarchical via parentId (UUID, inherited from SmrtHierarchical). Denormalised level recalculated by TagCollection.moveTag / mergeTag. JSON metadata. Hierarchy methods inherited: getParent(), getChildren(), getAncestors(), getDescendants(), getHierarchy(), moveTo(). Own helpers: getMetadata(), setMetadata(), updateMetadata()
TagAlias	Language-specific translations: tagSlug, alias, language (ISO 639-1), optional context

Collections (SmrtCollection)

Export	Description
TagCollection	CRUD + getOrCreate(), moveTag(), mergeTag(), cleanupUnused(), findWithGlobals()
TagAliasCollection	CRUD for tag aliases

Utilities

Export	Description
sanitizeSlug(input)	Clean and format slug strings
validateSlug(slug)	Validate slug format (lowercase, alphanumeric + hyphens)
generateUniqueSlug(name, context, collection)	Auto-numbered unique slug generation
calculateLevel(parentSlug, collection)	Determine hierarchy depth from parent
hasCircularReference(slug, parentSlug, collection)	Detect circular parent references

Types

Export	Description
TagOptions	Options for Tag constructor
TagAliasOptions	Options for TagAlias constructor
TagMetadata	Flexible metadata structure (colors, icons, statistics)
TagHierarchy	Complete hierarchy result (ancestors, current, descendants)

Dependencies

Package	Purpose
@happyvertical/smrt-core	ORM base (SmrtObject, SmrtCollection)
@happyvertical/smrt-tenancy	Optional tenant scoping