unique

Marks domain properties as members of unique keys through runtime metadata.

This package only records the uniqueness declaration. Schema converters, storage adapters, and other consumers decide how to name, group, validate, or enforce unique keys.

This documentation was written by an artificial intelligence and may contain errors or approximations. It has not yet been fully reviewed by a human. If anything seems unclear or incomplete, please feel free to contact the author of this package.

Requirements

• Node.js 24 or newer.
• TypeScript projects using decorator syntax must enable experimentalDecorators.

Installation

npm i @itrocks/unique

Usage

import { Unique }   from '@itrocks/unique'
import { uniqueOf } from '@itrocks/unique'

class Contact
{

	@Unique()
	email = ''

	name = ''

}

uniqueOf(Contact, 'email') // ''
uniqueOf(Contact, 'name')  // false

An empty string means that the consumer must choose the unique-key name. Pass a non-empty name when several properties must refer to the same logical key:

class Membership
{

	@Unique('organization_user')
	organization = ''

	@Unique('organization_user')
	user = ''

}

The package stores the same explicit name on both properties. Whether that represents a composite key, and in which property order, remains the responsibility of the metadata consumer.

Behaviour

• @Unique() stores an empty string to request consumer-defined naming.
• @Unique(name) stores name unchanged, including an explicitly empty string.
• uniqueOf() returns false when a property has no uniqueness metadata.
• Metadata declared on a base class is visible from derived classes and their instances. Decorating the same property on a derived class overrides the inherited value for that derived class.
• Importing the package only defines the metadata API; it does not register infrastructure or mutate schemas.

API

Unique

function Unique<T extends object>(name?: string): DecorateCaller<T>

Returns a property decorator that records unique-key metadata.

Parameters:

• name: Logical unique-key name. It defaults to '', which delegates naming to the consumer.

The decorator only records metadata and has no validation or persistence side effect.

uniqueOf

function uniqueOf<T extends object>(target: ObjectOrType<T>, property: keyof T): string | false

Reads the unique-key metadata associated with one property.

Parameters:

• target: Class or instance that owns or inherits the property.
• property: Property whose metadata is requested.

Returns:

• false when neither the target nor its inheritance chain declares the property unique.
• '' when the decorator delegates naming to the consumer.
• The explicit unique-key name otherwise.