@plasius/entity-manager

@plasius/entity-manager

Entity definitions and validation schemas for the Plasius ecosystem.

This package is part of the Plasius LTD selective open-source strategy. For more on our approach, see ADR-0013: Selective Open Source. This package is maintained as open source to foster community trust and enable integration, while the core Plasius platform remains proprietary.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Installation

npm install @plasius/entity-manager

Usage

import {
  userEntitySchema,
  PreferredDisplayOrder,
} from "@plasius/entity-manager";

const user = {
  type: "userEntity",
  version: "1.0",
  email: "[e-mail]",
  name: {
    firstName: "Alice",
    lastName: "Lovelace",
    displayName: "Alice L.",
    preferredDisplayOrder: PreferredDisplayOrder.DISPLAY_NAME,
  },
};

const result = userEntitySchema.validate(user);
if (!result.valid) {
  console.error(result.errors);
}

Editable Profile Validation Translations

Editable profile validation issues expose stable field and message keys with en-GB defaults resolved through @plasius/translations.

import {
  editableUserProfileValidationTranslationKeys,
  mapEditableUserProfileValidationErrors,
  translateEditableUserProfileValidationText,
  validateEditableUserProfile,
} from "@plasius/entity-manager";

const validation = validateEditableUserProfile(profile);
const mapped = mapEditableUserProfileValidationErrors(validation);

const message = translateEditableUserProfileValidationText(
  editableUserProfileValidationTranslationKeys.required,
  { field: "First name" },
);

console.log(mapped.issues[0]?.fieldKey, mapped.issues[0]?.messageKey, message);

Export Overview

Base entity

• baseEntitySchema, baseEntityShape, BaseEntity
• Required fields include partitionKey, id, entityType, createdAt, createdBy, and isDeleted (plus system type and version).
• Persistence-only fields such as partitionKey, createdBy, updatedBy, deletedBy, and deletedReason are marked internal and are omitted by default when calling schema.serialize(...).

User and permissions

• userEntitySchema, userNameSchema, userAvatarSchema
• Editable profile validation helpers and translation keys: validateEditableUserProfile, mapEditableUserProfileValidationErrors, editableUserProfileFieldTranslationKeys, editableUserProfileValidationTranslationKeys, entityManagerEnGbTranslations, translateEditableUserProfileValidationText
• settingsEntitySchema, permissionsEntitySchema, featureFlagEntitySchema, roleEntitySchema
• Enums: PreferredDisplayOrder, UserEmailPreferences, UserNotificationPreferences, Role, Scope

Assets

• assetEntitySchema, imageAssetEntitySchema, audioAssetEntitySchema, modelAssetEntitySchema, objectAssetEntitySchema

objectAssetEntitySchema includes object-specific fields for payload URL, optional thumbnail, optional format/size, and component wiring.

• Enums: AudioChannel, ModelAssetFormat

Components

• baseComponentSchema, physicsComponentSchema, animationComponentSchema, shadowComponentSchema, levelOfDetailComponentSchema
• Enum: ComponentTypes

Auth and translations

• authenticatedUserSchema, AuthProvider
• translatableSchema, supportedLanguagesSchema

Validators and utilities

• isValidAzureTableKey, isValidEntityType, validateAssetSchema
• validateFeatureFlagValue, validateSettingValue

Public Serialization

Entity schemas validate the full persisted entity shape, including internal audit and storage metadata. When returning data to clients, prefer schema.serialize(entity) so only public fields are included by default.

import { baseEntitySchema } from "@plasius/entity-manager";

const payload = baseEntitySchema.serialize({
  type: "baseEntity",
  version: "1.0.0",
  entityType: "baseEntity",
  partitionKey: "tenant-a",
  id: "row-1",
  createdAt: new Date().toISOString(),
  createdBy: "user-1",
  isDeleted: false,
});

// partitionKey and createdBy are omitted from the serialized payload.
console.log(payload);

Key Documentation

• Plasius Pillars
• Investor Brief
• Competition
• Architecture Decision Records (ADRs)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• Code of Conduct
• Contributor License Agreement

License

Licensed under the Apache-2.0 License.