Inspected version: 0.1.0 (private) · Part of the veap-repo monorepo (packages/veap-taggable).

@veap/taggable adds polymorphic tagging to any @veap/database model. Tags are stored in a shared tags table (with translatable name/slug/description via @veap/translatable) and attached through a taggables pivot.

Entry points #

The manifest exports ., ./migrations, ./ui and ./package.json.

Models #

Tag — extends TranslatableModel (static table = "tags", morphAlias = "tag", translatable = ["name", "slug", "description"]). Registered in MorphMap as tag.
- Tag.findOrCreateByName(name, locale = "pl") — looks up by translated name or slug and creates the tag (with a generated slug) when missing.
- slugifyTag(text) — the slug helper.
TagFactory / createTagFactory() — a faker-backed factory with pl/en translations.
TagSeeder — seeds 10 tags when the table is empty.

Mixins and base classes #

TaggableModel — a base class extending Model.
Taggable(Base) — the mixin form.
ITaggableModel / TaggableClass — typing helpers.
resolveTagIds(tags, locale = "pl") — resolves strings (names or UUIDs) and Tag instances to a de-duplicated id list.

Instance API #

Method	Behavior
`tags()`	The `morphToMany(Tag, "taggable")` relation.
`attachTags(tags, locale = "pl")`	Resolves and attaches tags.
`detachTags(tags?, locale = "pl")`	Detaches the given tags, or all when `tags` is omitted.
`syncTags(tags, locale = "pl")`	Replaces the attached set with exactly the given tags.

resolveTagIds treats a name-or-UUID string as an existing id when it matches a UUID pattern, otherwise it calls Tag.findOrCreateByName.

Query builder #

TaggableQueryBuilder extends ModelQueryBuilder:

whereTag(nameOrSlug, locale?)
whereAnyTag(namesOrSlugs, locale?)
whereAllTags(namesOrSlugs, locale?)
withTags() — eager-loads tags.translations.

Migrations #

The /migrations entry point creates the tags table and the polymorphic taggables pivot (tag_id, taggable_id, taggable_type, created_at) with a unique constraint and lookup indexes. down() preserves the shared tables.

UI (`./ui`)#

TagInput — a client tag input. value/onChange use tag names (onChange(tags: string[])); availableTags provides suggestions, and maxTags optionally caps the count.

Runtime and caveats #

Requires @veap/translatable migrations (the translations table) because tag names/slugs are translated.
attachTags/syncTags/whereTag default to the "pl" locale; pass the locale explicitly when your content is not Polish.