@mj-biz-apps/common-entities 5.4.0

package/README.md

@@ -0,0 +1,289 @@
+# MemberJunction Generated Entities
+
+This package contains automatically generated TypeScript entity classes that provide strongly-typed representations of database tables in the MemberJunction ecosystem.
+
+## Overview
+
+`mj_generatedentities` contains entity subclasses that are generated and maintained by MemberJunction's code generation system. These entities map directly to database tables and views, providing type-safe access to your data while abstracting away the complexity of data access.
+
+Key features:
+- **Type-safe data access**: All entity properties are strongly typed to match database columns
+- **Generated code**: Automatically maintained by MemberJunction to stay in sync with database schema
+- **Schema validation**: Uses Zod for runtime validation of entity data
+- **Extensible**: Base classes for extending with custom business logic
+- **MemberJunction integration**: Works seamlessly with MemberJunction's data context and API
+- **Webpack tree-shaking support**: Includes `LoadGeneratedEntities()` function to ensure proper bundling
+
+## Installation
+
+This package is a private package used internally within MemberJunction applications:
+
+```bash
+# Within the MemberJunction monorepo workspace
+npm install
+```
+
+Note: This package is marked as private (`"private": true`) in package.json and is not published to npm.
+
+## Dependencies
+
+- `@memberjunction/core` (v2.43.0): Core MemberJunction functionality including BaseEntity
+- `@memberjunction/global` (v2.43.0): Global utilities and constants
+- `zod` (v3.23.8): Schema validation library
+
+## Package Structure
+
+```
+mj_generatedentities/
+├── src/
+│   ├── index.ts                    # Main export file
+│   ├── generated/
+│   │   └── entity_subclasses.ts    # Auto-generated entity classes
+│   └── demo/
+│       └── demoContactEntitySubclass.ts  # Example of extending entities
+├── dist/                           # Compiled JavaScript output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Usage
+
+### Important: MemberJunction Entity Creation Pattern
+
+**Never directly instantiate entity classes**. Always use the Metadata system to ensure proper class registration:
+
+```typescript
+import { Metadata } from '@memberjunction/core';
+
+// ❌ Wrong - bypasses MJ class system
+const entity = new UserEntity();
+
+// ✅ Correct - uses MJ metadata system
+const md = new Metadata();
+const entity = await md.GetEntityObject<UserEntity>('Users');
+```
+
+### Loading Generated Entities for Webpack
+
+To ensure generated entities are included in webpack builds (avoiding tree-shaking issues):
+
+```typescript
+import { LoadGeneratedEntities } from 'mj_generatedentities';
+
+// Call this function early in your application initialization
+LoadGeneratedEntities();
+```
+
+### Working with Entity Classes
+
+```typescript
+import { Metadata, RunView } from '@memberjunction/core';
+
+// Load a single entity by ID
+async function getUserById(userId: string): Promise<UserEntity | null> {
+  const md = new Metadata();
+  const user = await md.GetEntityObject<UserEntity>('Users');
+  
+  if (await user.Load(userId)) {
+    return user;
+  }
+  return null;
+}
+
+// Load multiple entities with RunView
+async function getActiveUsers(): Promise<UserEntity[]> {
+  const rv = new RunView();
+  const result = await rv.RunView<UserEntity>({
+    EntityName: 'Users',
+    ExtraFilter: `IsActive = 1`,
+    OrderBy: 'CreatedAt DESC',
+    ResultType: 'entity_object'  // Returns entity objects, not raw data
+  });
+  
+  return result.Results;
+}
+
+// Update an entity
+async function updateUser(userId: string, updates: Partial<UserEntity>): Promise<boolean> {
+  const md = new Metadata();
+  const user = await md.GetEntityObject<UserEntity>('Users');
+  
+  if (await user.Load(userId)) {
+    // Apply updates
+    Object.assign(user, updates);
+    
+    // Save changes
+    const result = await user.Save();
+    return result.Success;
+  }
+  
+  return false;
+}
+```
+
+### Entity Relationships
+
+```typescript
+import { Metadata, RunView } from '@memberjunction/core';
+
+async function getUserWithRoles(userId: string) {
+  const md = new Metadata();
+  const user = await md.GetEntityObject<UserEntity>('Users');
+  
+  if (await user.Load(userId)) {
+    // Load related entities using RunView
+    const rv = new RunView();
+    const rolesResult = await rv.RunView<RoleEntity>({
+      EntityName: 'User Roles',
+      ExtraFilter: `UserID = '${userId}'`,
+      ResultType: 'entity_object'
+    });
+    
+    return {
+      user,
+      roles: rolesResult.Results
+    };
+  }
+  
+  return null;
+}
+```
+
+### Extending Generated Entities
+
+You can extend the generated entities with custom business logic. Use the `@RegisterClass` decorator to ensure proper registration:
+
+```typescript
+import { RegisterClass } from '@memberjunction/global';
+import { BaseEntity } from '@memberjunction/core';
+
+// Example from demo/demoContactEntitySubclass.ts
+@RegisterClass(BaseEntity, 'Contacts', 1)
+export class ContactEntity extends ContactBaseEntity {
+  // Override property getters/setters (must override both)
+  get FirstName(): string {
+    console.log("Getting FirstName from subclass");
+    return super.FirstName;
+  }
+  
+  set FirstName(value: string) {
+    super.FirstName = value;
+    console.log("Setting FirstName from subclass");
+  }
+  
+  // Add custom methods
+  async getFullName(): Promise<string> {
+    return `${this.FirstName} ${this.LastName}`;
+  }
+  
+  // Add custom validation
+  override async Validate(): Promise<ValidationResult> {
+    const result = await super.Validate();
+    
+    if (this.Email && !this.Email.includes('@')) {
+      result.Success = false;
+      result.Errors.push({
+        Source: 'Email',
+        Message: 'Email must contain @ symbol',
+        Type: ValidationErrorType.Failure
+      });
+    }
+    
+    return result;
+  }
+}
+```
+
+### Important Notes on Extending Entities
+
+1. **Always use `@RegisterClass` decorator** to register your subclass with MemberJunction
+2. **When overriding property getters/setters**, you MUST override both getter and setter
+3. **Call super methods** when overriding to maintain base functionality
+4. **Version parameter** in `@RegisterClass` allows for entity versioning
+
+### Zod Schema Validation
+
+Generated entities use Zod for schema validation:
+
+```typescript
+import { z } from 'zod';
+
+// Each generated entity includes a Zod schema
+const userSchema = z.object({
+  ID: z.string(),
+  FirstName: z.string(),
+  LastName: z.string(),
+  Email: z.string().email(),
+  IsActive: z.boolean(),
+  CreatedAt: z.date(),
+  UpdatedAt: z.date()
+});
+
+// Validate data before creating entities
+async function createUserFromData(userData: unknown) {
+  const result = userSchema.safeParse(userData);
+  
+  if (result.success) {
+    const md = new Metadata();
+    const user = await md.GetEntityObject<UserEntity>('Users');
+    await user.LoadFromData(result.data);
+    
+    const saveResult = await user.Save();
+    return saveResult.Success;
+  } else {
+    console.error('Validation errors:', result.error.format());
+    return false;
+  }
+}
+```
+
+## Entity Base Class Methods
+
+All generated entities inherit from `BaseEntity` and provide these key methods:
+
+| Method | Description |
+|--------|-------------|
+| `Load(id: CompositeKey)` | Loads an entity by its primary key |
+| `LoadFromData(data: any)` | Populates entity from a data object |
+| `Save(options?: EntitySaveOptions)` | Saves changes to the database |
+| `Delete()` | Deletes the entity from the database |
+| `Validate()` | Validates the entity, returns ValidationResult |
+| `GetFieldValue(fieldName: string)` | Gets the value of a specific field |
+| `SetFieldValue(fieldName: string, value: any)` | Sets the value of a specific field |
+| `TransactionMode` | Property to control transaction behavior |
+
+## Build Scripts
+
+```bash
+# Build the package
+npm run build
+
+# Development mode with auto-reload
+npm run start
+
+# Run tests (not implemented yet)
+npm test
+```
+
+## Code Generation
+
+This package is automatically maintained by MemberJunction's code generation system. The `entity_subclasses.ts` file is generated based on your database schema.
+
+**Important**: Do not manually edit files in the `generated/` directory as they will be overwritten during the next code generation cycle.
+
+To regenerate entities:
+1. Ensure your database schema is up to date
+2. Run the MemberJunction code generation tool from the appropriate package
+3. The generated files will be automatically updated
+
+## Development Notes
+
+- The package includes TypeScript declaration files (`*.d.ts`) in the dist folder
+- Source maps are generated for debugging
+- The `loadModule` export in entity_subclasses.ts ensures the module is valid even when empty
+- Use the demo file as a reference for creating custom entity subclasses
+
+## License
+
+ISC

package/dist/demo/demoContactEntitySubclass.d.ts

@@ -0,0 +1,11 @@
+import { BaseEntity } from "@memberjunction/core";
+declare class ContactBaseEntityStub extends BaseEntity {
+    get FirstName(): string;
+    set FirstName(value: string);
+}
+export declare class ContactDemoEntity extends ContactBaseEntityStub {
+    get FirstName(): string;
+    set FirstName(value: string);
+}
+export {};
+//# sourceMappingURL=demoContactEntitySubclass.d.ts.map

package/dist/demo/demoContactEntitySubclass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoContactEntitySubclass.d.ts","sourceRoot":"","sources":["../../src/demo/demoContactEntitySubclass.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKlD,cAAM,qBAAsB,SAAQ,UAAU;IAC1C,IAAI,SAAS,IAAI,MAAM,CAEtB;IACD,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,EAC1B;CACJ;AAKD,qBACa,iBAAkB,SAAQ,qBAAqB;IACxD,IAAI,SAAS,IAAI,MAAM,CAGtB;IACD,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,EAG1B;CACJ"}

package/dist/demo/demoContactEntitySubclass.js

@@ -0,0 +1,35 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+//import { ContactBaseEntity } from "../generated/entity_subclasses.js";
+import { BaseEntity } from "@memberjunction/core";
+import { RegisterClass } from "@memberjunction/global";
+// STUB base class-  you would DELETE this and use a real base class from ../generated/entity_subclasses instead
+class ContactBaseEntityStub extends BaseEntity {
+    get FirstName() {
+        return "";
+    }
+    set FirstName(value) {
+    }
+}
+// Super simple example of a sub-class for an example Contacts entity  doesn't do anything but you can see here you can do stuff with sub-class overrides
+// Also, important, if you're going to override the getter/setter for a property, you MUST call super.propertyName in the getter/setter AND you must also
+// override BOTH the getter and setter, otherwise you'll get a runtime error! This is because the getter/setter is actually a single property on the object
+let ContactDemoEntity = class ContactDemoEntity extends ContactBaseEntityStub /*here you would change this to sub-class the real base class from ../generated/entity_subclasses */ {
+    get FirstName() {
+        console.log("I'm getting the FirstName property from the sub-class!");
+        return super.FirstName;
+    }
+    set FirstName(value) {
+        super.FirstName = value;
+        console.log("I'm setting the FirstName property from the sub-class!");
+    }
+};
+ContactDemoEntity = __decorate([
+    RegisterClass(BaseEntity, 'Contacts', 1)
+], ContactDemoEntity);
+export { ContactDemoEntity };
+//# sourceMappingURL=demoContactEntitySubclass.js.map

package/dist/demo/demoContactEntitySubclass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoContactEntitySubclass.js","sourceRoot":"","sources":["../../src/demo/demoContactEntitySubclass.ts"],"names":[],"mappings":";;;;;;AAAA,qEAAqE;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,gHAAgH;AAChH,MAAM,qBAAsB,SAAQ,UAAU;IAC1C,IAAI,SAAS;QACT,OAAO,EAAE,CAAC;IACd,CAAC;IACD,IAAI,SAAS,CAAC,KAAa;IAC3B,CAAC;CACJ;AAED,yJAAyJ;AACzJ,yJAAyJ;AACzJ,2JAA2J;AAEpJ,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,qBAAqB,CAAC,oGAAoG;IAC7J,IAAI,SAAS;QACT,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAA;QACrE,OAAO,KAAK,CAAC,SAAS,CAAC;IAC3B,CAAC;IACD,IAAI,SAAS,CAAC,KAAa;QACvB,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAA;IACzE,CAAC;CACJ,CAAA;AATY,iBAAiB;IAD7B,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;GAC5B,iBAAiB,CAS7B"}