TypeScript icon, indicating that this package has built-in type declarations

2.1.0 • Public • Published

Entity-ref 📍

Create small references to entities

CircleCI npm version Coverage Status License: MIT

Example code

Helper to create consistent entity references used for uniquely identify entity without all its data.

Especially useful if you need to create an address/reference of any kind of entity in places like:

Use cases

  • audit logs
  • targeting entities in cascade actions for @pallad/cascade
  • targeting in ACL
  • passing entity reference through messaging channels without sending entire entity
  • base for enigmatic IDs


Join our discord server


npm install @pallad/entity-ref


The most useful part of this lib is createFactory responsible for creating entity ref, adding extra factories and testing the type.

const userRefFactory = createFactory(
		'user', // indicate type name
		(id: string) => ({id}), // main factory that also describes the shape of entity ref data

// create ref for given ID
const ref = userRefFactory('1'); // {type: 'user', data: {id: '1'}}

Testing type

You can check if ref is actually a ref for given type using .is method.

const articleRefFactory = createFactory(
		(id: string) => ({id}),

const ref = articleRefFactory('1'); // {type: 'article', data: {id: '1'}}

userRefFactory.is(ref) // false
articleRefFactory.is(ref) // true

.is plays a role of type guard as well.

if (articleRefFactory.is(ref)) {
    ref.type // 'article';
	ref.data.id // 👍 typescript knows shape of article refs so no error here
	ref.data.someOtherProperty // ⚠️ this fails

Extra factories

Third argument of createFactory accepts an object with extra factories in final factory object.

class Article {
	readonly id: string;
	readonly title: string;
	readonly createdAt: Date;
	readonly updatedAt: Date;
	readonly authorId: string;

	constructor(data: Article) {
		Object.assign(this, data);

const articleRefFactory = createFactory(
		(id: string) => ({id}),
			fromEntity({id}: Article) {
				return {id}; // note that it has to return the same data as above

// {type: 'article', data: {id: '10'}}

		new Article({
			id: '10',
			title: 'Example title',
			createdAt: new Date(),
			updatedAt: new Date(),
			authorId: '20'
// {type: 'article', data: {id: '10'}}

Hierarchical data

Storing only main id in entity seems to be useless in many scenarious but lets imagine that every article belongs to organization or workspace so it would be nice to return that information in ref as well.

const articleRefFactory = createFactory(
    (id: string, workspaceId: string) => ({id, workspaceId}),
        fromEntity({id, workspaceId}: Article) {
            return {id, workspaceId};


Targeting in ACL

import {EntityRef} from "@pallad/entity-ref";

export function hasReadPermission(entityRef: EntityRef<any, any>) {
    if (entityRef.type === 'article') {
        // TODO perform extra checks
    } else if (entityRef.type === 'user') {
        // TODO perform extra checks
    return false;

// controller.ts
export default {
    findArticle(id: string) {
        if (!hasReadPermission(articleRefFactory(id))) {
            throw new Error('Insufficient permissions');
        // fetch and return article

Audit log

import {EntityRef} from "@pallad/entity-ref";

export function articleCreated(article: Article) {
    return entityCreated(articleRefFactory.fromEntity(article));

export function entityCreated(ref: EntityRef<any, any>) {
    return createAuditLog({
        name: 'entity.created',

Enigmatic IDs

import {EntityRef} from "@pallad/entity-ref";

export function decodeId(id: string): EntityRef<any, {id: string}> {
    const [type, id] = Buffer.from(id, 'base64').toString('utf8').split('-');
    return EntityRef.create(type, {id});

export function encodeId(ref: EntityRef<any, {id: string}>) {
    return Buffer.from(`${ref.type}-${ref.data.id}`).toString('base64');

encodeId(articleRefFactory('1')) // 'YXJ0aWNsZS0x'
decodeId('YXJ0aWNsZS0x') // {type: 'article', data: {id: '1'}}

Package Sidebar


npm i @pallad/entity-ref

Weekly Downloads






Unpacked Size

46.5 kB

Total Files


Last publish


  • wookieb