@klerick/json-api-nestjs-sdk 10.0.0-beta.8 → 10.0.0

package/README.md

@@ -16,6 +16,7 @@ Type-safe TypeScript/JavaScript client for consuming [JSON:API](https://jsonapi.
 - 🔍 **Advanced Filtering** - Rich query builder with operators (eq, ne, in, like, gt, lt, etc.)
 - 📦 **Relationship Handling** - Easy include, sparse fieldsets, and relationship management
 - ⚡ **Atomic Operations** - Batch multiple operations in a single request with rollback support
+- 📤 **Meta Support** - Pass additional business logic data with requests (JSON:API spec compliant)
 - 🌐 **Multiple HTTP Clients** - Works with Axios, Fetch API, and Angular HttpClient
 - 📄 **Pagination & Sorting** - Built-in support for pagination and multi-field sorting
 - 🔄 **Observable or Promise** - Choose your async style (RxJS Observable or native Promise)
@@ -34,6 +35,11 @@ Type-safe TypeScript/JavaScript client for consuming [JSON:API](https://jsonapi.
   - [Updating Resources](#updating-resources)
   - [Deleting Resources](#deleting-resources)
   - [Relationship Operations](#relationship-operations)
+- [Working with Plain Objects](#-working-with-plain-objects)
+  - [Using entity() Method](#using-entity-method)
+  - [Using String Type Names](#using-string-type-names)
+- [Nullifying Relationships](#-nullifying-relationships)
+- [Clearing To-Many Relationships](#-clearing-to-many-relationships)
 - [Query Options](#-query-options)
   - [Filtering](#filtering)
   - [Sorting](#sorting)
@@ -41,6 +47,10 @@ Type-safe TypeScript/JavaScript client for consuming [JSON:API](https://jsonapi.
   - [Including Relationships](#including-relationships)
   - [Sparse Fieldsets](#sparse-fieldsets)
 - [Atomic Operations](#-atomic-operations)
+- [Meta Support](#-meta-support)
+  - [Regular Operations with Meta](#regular-operations-with-meta)
+  - [Entity Chain with Meta](#entity-chain-with-meta)
+  - [Atomic Operations with Meta](#atomic-operations-with-meta)
 - [Examples](#-examples)
 
 
@@ -78,10 +88,10 @@ const jsonSdk = JsonApiJs(
 
 // 3. Use SDK
 // Fetch all users
-const users = await jsonSdk.jonApiSdkService.getAll(Users);
+const users = await jsonSdk.jsonApiSdkService.getAll(Users);
 
 // Fetch with filtering and relationships
-const activeUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
+const activeUsers = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       isActive: { [FilterOperand.eq]: 'true' }
@@ -91,7 +101,7 @@ const activeUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // Get one user
-const user = await jsonSdk.jonApiSdkService.getOne(Users, '1', {
+const user = await jsonSdk.jsonApiSdkService.getOne(Users, '1', {
   include: ['addresses', 'comments', 'roles', 'manager']
 });
 
@@ -102,14 +112,14 @@ newUser.lastName = 'Doe';
 newUser.login = 'johndoe';
 newUser.isActive = true;
 
-const createdUser = await jsonSdk.jonApiSdkService.postOne(newUser);
+const createdUser = await jsonSdk.jsonApiSdkService.postOne(newUser);
 
 // Update a user
 createdUser.firstName = 'Jane';
-const updatedUser = await jsonSdk.jonApiSdkService.patchOne(createdUser);
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(createdUser);
 
 // Delete a user
-await jsonSdk.jonApiSdkService.deleteOne(createdUser);
+await jsonSdk.jsonApiSdkService.deleteOne(createdUser);
 ```
 
 ### Angular Setup
@@ -128,6 +138,8 @@ import { Component, inject } from '@angular/core';
 import { bootstrapApplication } from '@angular/platform-browser';
 
 // 1. Configure in your main.ts or app.config.ts
+
+// Option A: Direct configuration object
 const angularConfig = {
   apiHost: 'http://localhost:3000',
   idKey: 'id',
@@ -143,6 +155,23 @@ bootstrapApplication(AppComponent, {
   ],
 }).catch((err) => console.error(err));
 
+// Option B: Factory function (useful for dynamic configuration)
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideHttpClient(withFetch()),
+    provideJsonApi(() => {
+      const env = inject(EnvironmentService);
+      return {
+        apiHost: env.apiUrl,
+        idKey: 'id',
+        apiPrefix: 'api',
+        operationUrl: 'operation',
+        dateFields: ['createdAt', 'updatedAt']
+      };
+    })
+  ],
+}).catch((err) => console.error(err));
+
 // 2. Use in your components
 @Component({
   standalone: true,
@@ -186,6 +215,10 @@ type JsonSdkConfig = {
 type JsonConfig = JsonSdkConfig & {
   adapter?: HttpInnerClient; // HTTP client adapter (default: fetch)
 }
+
+// Angular: provideJsonApi accepts config or factory function
+type JsonSdkConfigFactory = () => JsonSdkConfig;
+type JsonSdkConfigOrFactory = JsonSdkConfig | JsonSdkConfigFactory;
 ```
 
 ### HTTP Adapters
@@ -225,10 +258,10 @@ Fetch all resources with optional filtering, sorting, and relationships.
 import { FilterOperand } from '@klerick/json-api-nestjs-sdk';
 
 // Fetch all users
-const users = await jsonSdk.jonApiSdkService.getAll(Users);
+const users = await jsonSdk.jsonApiSdkService.getAll(Users);
 
 // With filtering
-const activeUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
+const activeUsers = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       isActive: { [FilterOperand.eq]: 'true' },
@@ -239,7 +272,7 @@ const activeUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // Filter by relationship
-const usersWithRoles = await jsonSdk.jonApiSdkService.getAll(Users, {
+const usersWithRoles = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       id: { [FilterOperand.in]: ['1', '2'] }
@@ -257,7 +290,7 @@ const usersWithRoles = await jsonSdk.jonApiSdkService.getAll(Users, {
 Fetch resources with pagination (returns paginated results).
 
 ```typescript
-const firstPage = await jsonSdk.jonApiSdkService.getList(Users, {
+const firstPage = await jsonSdk.jsonApiSdkService.getList(Users, {
   page: {
     number: 1,
     size: 10
@@ -269,7 +302,7 @@ const firstPage = await jsonSdk.jonApiSdkService.getList(Users, {
   }
 });
 
-const secondPage = await jsonSdk.jonApiSdkService.getList(Users, {
+const secondPage = await jsonSdk.jsonApiSdkService.getList(Users, {
   page: {
     number: 2,
     size: 10
@@ -288,15 +321,15 @@ Fetch a single resource by ID.
 
 ```typescript
 // Simple fetch
-const user = await jsonSdk.jonApiSdkService.getOne(Users, '1');
+const user = await jsonSdk.jsonApiSdkService.getOne(Users, '1');
 
 // With relationships
-const userWithRelations = await jsonSdk.jonApiSdkService.getOne(Users, '1', {
+const userWithRelations = await jsonSdk.jsonApiSdkService.getOne(Users, '1', {
   include: ['addresses', 'comments', 'roles', 'manager']
 });
 
 // With sparse fieldsets
-const userPartial = await jsonSdk.jonApiSdkService.getOne(Users, '1', {
+const userPartial = await jsonSdk.jsonApiSdkService.getOne(Users, '1', {
   fields: {
     users: ['firstName', 'lastName', 'email']
   }
@@ -317,7 +350,17 @@ newUser.lastName = 'Doe';
 newUser.login = 'johndoe';
 newUser.isActive = true;
 
-const createdUser = await jsonSdk.jonApiSdkService.postOne(newUser);
+const createdUser = await jsonSdk.jsonApiSdkService.postOne(newUser);
+
+// Create with client-generated ID
+// Note: Server must have `allowSetId: true` option enabled
+const userWithId = new Users();
+userWithId.id = 'my-custom-uuid';
+userWithId.firstName = 'Jane';
+userWithId.lastName = 'Doe';
+userWithId.login = 'janedoe';
+
+const createdUserWithId = await jsonSdk.jsonApiSdkService.postOne(userWithId);
 
 // Create with relationships
 const newAddress = new Addresses();
@@ -325,7 +368,7 @@ newAddress.city = 'New York';
 newAddress.state = 'NY';
 newAddress.country = 'USA';
 
-const savedAddress = await jsonSdk.jonApiSdkService.postOne(newAddress);
+const savedAddress = await jsonSdk.jsonApiSdkService.postOne(newAddress);
 
 const user = new Users();
 user.firstName = 'Jane';
@@ -333,7 +376,7 @@ user.lastName = 'Doe';
 user.login = 'janedoe';
 user.addresses = savedAddress; // Set relationship
 
-const createdUser = await jsonSdk.jonApiSdkService.postOne(user);
+const createdUser = await jsonSdk.jsonApiSdkService.postOne(user);
 ```
 
 ### Updating Resources
@@ -345,13 +388,13 @@ Update an existing resource.
 ```typescript
 // Update attributes
 user.firstName = 'Updated Name';
-const updatedUser = await jsonSdk.jonApiSdkService.patchOne(user);
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(user);
 
 // Update relationships
-const newAddress = await jsonSdk.jonApiSdkService.postOne(addressEntity);
+const newAddress = await jsonSdk.jsonApiSdkService.postOne(addressEntity);
 user.addresses = newAddress;
 
-const updatedUser = await jsonSdk.jonApiSdkService.patchOne(user);
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(user);
 ```
 
 ### Deleting Resources
@@ -361,7 +404,7 @@ const updatedUser = await jsonSdk.jonApiSdkService.patchOne(user);
 Delete a resource.
 
 ```typescript
-await jsonSdk.jonApiSdkService.deleteOne(user);
+await jsonSdk.jsonApiSdkService.deleteOne(user);
 ```
 
 ### Relationship Operations
@@ -372,13 +415,196 @@ Remove relationships without deleting the related resources.
 
 ```typescript
 // Remove all roles from user
-await jsonSdk.jonApiSdkService.deleteRelationships(user, 'roles');
+await jsonSdk.jsonApiSdkService.deleteRelationships(user, 'roles');
 
 // Remove manager from user
-await jsonSdk.jonApiSdkService.deleteRelationships(user, 'manager');
+await jsonSdk.jsonApiSdkService.deleteRelationships(user, 'manager');
 
 // Remove all comments from user
-await jsonSdk.jonApiSdkService.deleteRelationships(user, 'comments');
+await jsonSdk.jsonApiSdkService.deleteRelationships(user, 'comments');
+```
+
+---
+
+## 🏗️ Working with Plain Objects
+
+In monorepo environments or when sharing types between frontend and backend, you may want to use plain TypeScript types/interfaces instead of classes. The SDK provides tools to work with plain objects while maintaining full type safety.
+
+### Using entity() Method
+
+The `entity()` method creates a properly typed entity instance from a plain object. This is essential when:
+- You share types (not classes) between frontend and backend
+- The SDK needs to identify the resource type at runtime (via `constructor.name`)
+
+```typescript
+import { JsonApiJs } from '@klerick/json-api-nestjs-sdk';
+
+// Shared type (not a class)
+interface User {
+  id?: number;
+  firstName: string;
+  lastName: string;
+  login: string;
+  manager?: User | null;
+}
+
+const jsonSdk = JsonApiJs({ apiHost: 'http://localhost:3000', apiPrefix: 'api' }, true);
+
+// Create entity from plain object - chainable API
+const createdUser = await jsonSdk.jsonApiSdkService
+  .entity<User>('Users', {
+    firstName: 'John',
+    lastName: 'Doe',
+    login: 'johndoe'
+  })
+  .postOne();
+
+// Update entity - chainable API
+const updatedUser = await jsonSdk.jsonApiSdkService
+  .entity<User>('Users', {
+    id: 1,
+    firstName: 'Jane'
+  })
+  .patchOne();
+
+// Delete entity - chainable API
+await jsonSdk.jsonApiSdkService
+  .entity<User>('Users', { id: 1 })
+  .deleteOne();
+
+// Work with relationships
+const userRelations = await jsonSdk.jsonApiSdkService
+  .entity<User>('Users', { id: 1 })
+  .getRelationships('manager');
+```
+
+**Raw mode** - get the entity instance without chaining:
+
+```typescript
+// Get raw entity instance (third argument = true)
+const userEntity = jsonSdk.jsonApiSdkService.entity<User>('Users', {
+  firstName: 'John',
+  lastName: 'Doe',
+  login: 'johndoe'
+}, true);
+
+// Now use it with standard SDK methods
+const created = await jsonSdk.jsonApiSdkService.postOne(userEntity);
+```
+
+### Using String Type Names
+
+GET methods also accept string type names instead of classes:
+
+```typescript
+// Using string type name
+const users = await jsonSdk.jsonApiSdkService.getAll<User>('Users', {
+  include: ['manager']
+});
+
+const user = await jsonSdk.jsonApiSdkService.getOne<User>('Users', '1', {
+  include: ['manager']
+});
+
+const userList = await jsonSdk.jsonApiSdkService.getList<User>('Users', {
+  page: { number: 1, size: 10 }
+});
+```
+
+---
+
+## 🔗 Nullifying Relationships
+
+To clear a relationship (set it to `null`), use the `nullRef()` function. This is necessary because the SDK distinguishes between:
+- **Missing relationship** - not included in the request (no change)
+- **Null relationship** - explicitly set to `null` (clear the relationship)
+
+```typescript
+import { JsonApiJs, nullRef } from '@klerick/json-api-nestjs-sdk';
+
+interface User {
+  id?: number;
+  firstName: string;
+  manager?: User | null;
+}
+
+const jsonSdk = JsonApiJs({ apiHost: 'http://localhost:3000', apiPrefix: 'api' }, true);
+
+// Clear the manager relationship
+const user = jsonSdk.jsonApiSdkService.entity<User>('Users', {
+  id: 1,
+  firstName: 'John',
+  manager: nullRef()  // This will send { data: null } for the relationship
+}, true);
+
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(user);
+// Result: user.manager is now null
+```
+
+**How it works:**
+- `nullRef()` returns a special marker object that TypeScript sees as `null`
+- At runtime, the SDK detects this marker and generates `{ data: null }` in the JSON:API request body
+- The server then clears the relationship
+
+**Without nullRef:**
+```typescript
+// This won't clear the relationship - it will be ignored
+const user = jsonSdk.jsonApiSdkService.entity<User>('Users', {
+  id: 1,
+  firstName: 'John',
+  // manager is undefined - not included in request
+}, true);
+```
+
+**With nullRef:**
+```typescript
+// This explicitly clears the relationship
+const user = jsonSdk.jsonApiSdkService.entity<User>('Users', {
+  id: 1,
+  firstName: 'John',
+  manager: nullRef()  // Generates: relationships: { manager: { data: null } }
+}, true);
+```
+
+## 🔗 Clearing To-Many Relationships
+
+To clear all items from a to-many relationship (ManyToMany, OneToMany), use the `emptyArrayRef()` function:
+
+```typescript
+import { JsonApiJs, emptyArrayRef } from '@klerick/json-api-nestjs-sdk';
+
+interface User {
+  id?: number;
+  firstName: string;
+  roles?: Role[];
+}
+
+const jsonSdk = JsonApiJs({ apiHost: 'http://localhost:3000', apiPrefix: 'api' }, true);
+
+// Clear all roles from user
+const user = jsonSdk.jsonApiSdkService.entity<User>('Users', {
+  id: 1,
+  firstName: 'John',
+  roles: emptyArrayRef()  // This will send { data: [] } for the relationship
+}, true);
+
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(user);
+// Result: user.roles is now an empty array
+```
+
+**Why emptyArrayRef is needed:**
+- An empty array `[]` would be treated as an attribute (not a relationship)
+- `emptyArrayRef()` marks it as a relationship that should be cleared
+- At runtime, the SDK generates `{ data: [] }` in the JSON:API request body
+
+**Comparison:**
+```typescript
+// ❌ This won't work - empty array treated as attribute
+const user = { id: 1, roles: [] };
+
+// ✅ This works - explicitly clears the relationship
+const user = { id: 1, roles: emptyArrayRef() };
+// Generates: relationships: { roles: { data: [] } }
 ```
 
 ---
@@ -408,7 +634,7 @@ enum FilterOperand {
 
 ```typescript
 // Equal
-const users = await jsonSdk.jonApiSdkService.getAll(Users, {
+const users = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       isActive: { [FilterOperand.eq]: 'true' }
@@ -417,7 +643,7 @@ const users = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // Not equal
-const inactiveUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
+const inactiveUsers = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       isActive: { [FilterOperand.ne]: 'true' }
@@ -426,7 +652,7 @@ const inactiveUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // In array
-const specificUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
+const specificUsers = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       id: { [FilterOperand.in]: ['1', '2', '3'] }
@@ -435,7 +661,7 @@ const specificUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // LIKE search
-const searchUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
+const searchUsers = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       login: { [FilterOperand.like]: 'john' }
@@ -444,7 +670,7 @@ const searchUsers = await jsonSdk.jonApiSdkService.getAll(Users, {
 });
 
 // Check null/not null
-const usersWithManager = await jsonSdk.jonApiSdkService.getAll(Users, {
+const usersWithManager = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       manager: { [FilterOperand.ne]: null }
@@ -452,7 +678,7 @@ const usersWithManager = await jsonSdk.jonApiSdkService.getAll(Users, {
   }
 });
 
-const usersWithoutManager = await jsonSdk.jonApiSdkService.getAll(Users, {
+const usersWithoutManager = await jsonSdk.jsonApiSdkService.getAll(Users, {
   filter: {
     target: {
       manager: { [FilterOperand.eq]: null }
@@ -465,7 +691,7 @@ const usersWithoutManager = await jsonSdk.jonApiSdkService.getAll(Users, {
 
 ```typescript
 // Sort by single field
-const users = await jsonSdk.jonApiSdkService.getList(Users, {
+const users = await jsonSdk.jsonApiSdkService.getList(Users, {
   sort: {
     target: {
       id: 'ASC'
@@ -474,7 +700,7 @@ const users = await jsonSdk.jonApiSdkService.getList(Users, {
 });
 
 // Sort by multiple fields
-const sortedUsers = await jsonSdk.jonApiSdkService.getList(Users, {
+const sortedUsers = await jsonSdk.jsonApiSdkService.getList(Users, {
   sort: {
     target: {
       createdAt: 'DESC',
@@ -487,7 +713,7 @@ const sortedUsers = await jsonSdk.jonApiSdkService.getList(Users, {
 ### Pagination
 
 ```typescript
-const paginatedUsers = await jsonSdk.jonApiSdkService.getList(Users, {
+const paginatedUsers = await jsonSdk.jsonApiSdkService.getList(Users, {
   page: {
     number: 1,  // Page number (1-indexed)
     size: 20    // Items per page
@@ -499,17 +725,17 @@ const paginatedUsers = await jsonSdk.jonApiSdkService.getList(Users, {
 
 ```typescript
 // Include single relationship
-const users = await jsonSdk.jonApiSdkService.getAll(Users, {
+const users = await jsonSdk.jsonApiSdkService.getAll(Users, {
   include: ['addresses']
 });
 
 // Include multiple relationships
-const usersWithAll = await jsonSdk.jonApiSdkService.getAll(Users, {
+const usersWithAll = await jsonSdk.jsonApiSdkService.getAll(Users, {
   include: ['addresses', 'roles', 'comments', 'manager']
 });
 
 // Include nested relationships
-const usersWithNested = await jsonSdk.jonApiSdkService.getAll(Users, {
+const usersWithNested = await jsonSdk.jsonApiSdkService.getAll(Users, {
   include: ['addresses', 'manager.addresses', 'roles']
 });
 ```
@@ -519,7 +745,7 @@ const usersWithNested = await jsonSdk.jonApiSdkService.getAll(Users, {
 Request only specific fields to reduce payload size.
 
 ```typescript
-const users = await jsonSdk.jonApiSdkService.getAll(Users, {
+const users = await jsonSdk.jsonApiSdkService.getAll(Users, {
   fields: {
     users: ['firstName', 'lastName', 'email'],
     addresses: ['city', 'country']
@@ -614,28 +840,255 @@ const result = await jsonSdk
 // result[3] - array of all comment IDs after addition
 ```
 
-### Using Temporary IDs (lid)
+### Using Local Identifiers (lid)
 
-Reference resources created within the same atomic request using temporary IDs.
+Create and reference resources within the same atomic request using local identifiers (`lid`). This allows you to establish relationships between resources being created in a single batch operation.
 
+**How it works:**
+1. Assign a temporary ID to the resource (any unique value - number or string)
+2. Reference this ID in relationships of other resources in the same request
+3. Server automatically replaces temporary IDs with real database IDs
+
+**Example - Numeric lid:**
 ```typescript
 const address = new Addresses();
 address.city = 'Boston';
-address.id = 10000; // Temporary ID
+address.id = 10000; // Temporary ID (lid)
 
 const user = new Users();
 user.firstName = 'Alice';
-user.addresses = address; // Reference by temp ID
+user.addresses = address; // Reference resource by temporary ID
 
 const [createdAddress, createdUser] = await jsonSdk
   .atomicFactory()
-  .postOne(address)
+  .postOne(address)  // First operation: create address with lid=10000
+  .postOne(user)     // Second operation: reference address via lid
+  .run();
+
+// Server assigns real IDs and maintains relationships
+console.log(createdAddress.id); // Real ID (e.g., 42)
+console.log(createdUser.addresses.id); // Same real ID (42)
+```
+
+**Example - UUID lid (for entities with UUID primary keys):**
+```typescript
+const book1 = new BookList();
+book1.id = '550e8400-e29b-41d4-a716-446655440000'; // Temporary UUID (lid)
+book1.title = 'TypeScript Handbook';
+
+const book2 = new BookList();
+book2.id = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // Another temporary UUID (lid)
+book2.title = 'Advanced Node.js';
+
+const user = new Users();
+user.firstName = 'John';
+user.books = [book1, book2]; // Reference both books by their temporary UUIDs
+
+const [createdBook1, createdBook2, createdUser] = await jsonSdk
+  .atomicFactory()
+  .postOne(book1)
+  .postOne(book2)
   .postOne(user)
   .run();
 
-// Server assigns real IDs
-console.log(createdAddress.id); // Real ID (e.g., 1)
-console.log(createdUser.addresses.id); // Same real ID
+// All temporary IDs are used as actual IDs (for UUID fields)
+// or replaced with real IDs (for autoincrement fields)
+console.log(createdBook1.id); // UUID from lid
+console.log(createdBook2.id); // UUID from lid
+console.log(createdUser.books.map(b => b.id)); // Both book UUIDs
+```
+
+**Important notes:**
+- Local identifiers (lid) are only valid within a single atomic request
+- The SDK automatically handles lid assignment in the request body
+- For numeric IDs: lid is replaced with the actual database-generated ID
+- For UUID IDs: lid can be used as the actual ID (if server has `allowSetId: true`)
+
+---
+
+## 📤 Meta Support
+
+The SDK supports passing `meta` objects with requests to send additional business logic data that doesn't belong to the entity itself, according to [JSON:API specification](https://jsonapi.org/format/#document-meta).
+
+### Regular Operations with Meta
+
+```typescript
+// POST with meta
+const newUser = new Users();
+newUser.firstName = 'John';
+newUser.lastName = 'Doe';
+newUser.login = 'johndoe';
+
+const createdUser = await jsonSdk.jsonApiSdkService.postOne(newUser, {
+  source: 'import',
+  batchId: '12345'
+});
+
+// Request body:
+{
+  "data": {
+    "type": "users",
+    "attributes": { "firstName": "John", "lastName": "Doe", "login": "johndoe" }
+  },
+  "meta": {
+    "source": "import",
+    "batchId": "12345"
+  }
+}
+
+// PATCH with meta
+user.firstName = 'Jane';
+const updatedUser = await jsonSdk.jsonApiSdkService.patchOne(user, {
+  updatedBy: 'admin',
+  reason: 'name correction'
+});
+
+// Relationship operations with meta
+await jsonSdk.jsonApiSdkService.postRelationships(user, 'roles', {
+  addedBy: 'admin',
+  timestamp: Date.now()
+});
+
+await jsonSdk.jsonApiSdkService.patchRelationships(user, 'roles', {
+  source: 'sync',
+  syncId: 'abc123'
+});
+
+await jsonSdk.jsonApiSdkService.deleteRelationships(user, 'roles', {
+  removedBy: 'admin',
+  reason: 'access revoked'
+});
+```
+
+**Important:** `deleteOne()` does NOT support meta because HTTP DELETE for resources has no body according to JSON:API spec. However, `deleteRelationships()` DOES support meta because relationship deletion endpoints use a request body.
+
+### Entity Chain with Meta
+
+```typescript
+// Chain mode - Observable
+const user = await jsonSdk.jsonApiSdkService
+  .entity('Users', {
+    firstName: 'John',
+    lastName: 'Doe',
+    login: 'johndoe'
+  })
+  .postOne({ source: 'mobile-app', version: '2.0' });
+
+// Update with meta
+await jsonSdk.jsonApiSdkService
+  .entity('Users', { id: 1, firstName: 'Jane' })
+  .patchOne({ updatedBy: 'user-123' });
+
+// Relationship operations with meta
+await jsonSdk.jsonApiSdkService
+  .entity('Users', user)
+  .patchRelationships('roles', { operation: 'bulk-update' });
+```
+
+### Atomic Operations with Meta
+
+Each operation in an atomic request can have its own meta:
+
+```typescript
+const address1 = new Addresses();
+address1.id = 999; // Local identifier (lid)
+address1.city = 'New York';
+
+const address2 = new Addresses();
+address2.id = 1000; // Local identifier (lid)
+address2.city = 'Boston';
+
+const user1 = new Users();
+user1.firstName = 'Alice';
+user1.addresses = address1;
+
+const user2 = new Users();
+user2.firstName = 'Bob';
+user2.addresses = address2;
+
+const [addr1, addr2, createdUser1, createdUser2] = await jsonSdk
+  .atomicFactory()
+  .postOne(address1)
+  .postOne(address2)
+  .postOne(user1, { source: 'import', priority: 'high' })      // User 1 with meta
+  .postOne(user2, { source: 'import', priority: 'normal' })    // User 2 with different meta
+  .run();
+
+// Request body:
+{
+  "atomic:operations": [
+    {
+      "op": "add",
+      "ref": { "type": "addresses", "lid": "999" },
+      "data": { "type": "addresses", "attributes": { "city": "New York" } }
+    },
+    {
+      "op": "add",
+      "ref": { "type": "addresses", "lid": "1000" },
+      "data": { "type": "addresses", "attributes": { "city": "Boston" } }
+    },
+    {
+      "op": "add",
+      "ref": { "type": "users" },
+      "data": {
+        "type": "users",
+        "attributes": { "firstName": "Alice" },
+        "relationships": { "addresses": { "data": { "type": "addresses", "id": "999" } } }
+      },
+      "meta": { "source": "import", "priority": "high" }  // Meta for operation 3
+    },
+    {
+      "op": "add",
+      "ref": { "type": "users" },
+      "data": {
+        "type": "users",
+        "attributes": { "firstName": "Bob" },
+        "relationships": { "addresses": { "data": { "type": "addresses", "id": "1000" } } }
+      },
+      "meta": { "source": "import", "priority": "normal" }  // Meta for operation 4
+    }
+  ]
+}
+```
+
+### Meta with Entity Chain in Atomic Operations
+
+```typescript
+const addressEntity = jsonSdk.jsonApiSdkService.entity('Addresses', {
+  id: 999,
+  city: 'New York'
+}, true);
+
+const userEntity = jsonSdk.jsonApiSdkService.entity('Users', {
+  firstName: 'Alice',
+  addresses: jsonSdk.jsonApiSdkService.entity('Addresses', { id: 999 }, true)
+}, true);
+
+const [createdAddress, createdUser] = await jsonSdk
+  .atomicFactory()
+  .postOne(addressEntity)
+  .postOne(userEntity, { source: 'import', batchId: '12345' })
+  .run();
+```
+
+### Operations WITHOUT Meta Support
+
+The following operations do NOT accept meta parameter:
+
+```typescript
+// ❌ deleteOne - HTTP DELETE has no body
+await jsonSdk.jsonApiSdkService.deleteOne(user);
+// Cannot pass meta here
+
+// ❌ deleteOne in atomic operations
+await jsonSdk.atomicFactory()
+  .deleteOne(user)  // No meta parameter
+  .run();
+
+// ✅ But deleteRelationships DOES support meta (has body)
+await jsonSdk.jsonApiSdkService.deleteRelationships(user, 'roles', {
+  removedBy: 'admin'
+});
 ```
 
 ---