npm package: @schematize/client-jsonapi
Description: Schematize JSONAPI Client Library
Author: Benjamin Bytheway
Latest version: 0.6.3

# @schematize/client-jsonapi

A client-side JSON:API library that provides object-relational mapping (ORM) functionality for UML metamodel instances over HTTP.  This package extends the Metamodel library with JSON:API persistence capabilities, allowing you to save, fetch, and manage instances with automatic change tracking, lazy loading, and authentication support.

## Features

- **JSON:API Compliance**: Full support for JSON:API specification
- **Instance Management**: Create, save, delete, and track changes to UML instances
- **Lazy Loading**: Properties are loaded on-demand with caching and expiration
- **Change Tracking**: Automatic detection of dirty instances that need saving
- **Advanced Link Management**: Enhanced association link tracking with automatic cleanup and bidirectional synchronization
- **Query Interface**: Find instances by ID or with complex filters
- **Authentication Support**: Built-in OAuth and authorization handling
- **Event System**: Listen to instance changes, saves, and deletions
- **Symbol-based Configuration**: Use symbols to configure base URLs and authentication
- **Cross-platform**: Works in both browser and Node.js environments

## Dependencies

- `@schematize/refs`
- `@schematize/instance.js`
- `@schematize/metamodel`

## Installation

```bash
npm install @schematize/client-jsonapi
```

## Usage

### Basic Setup

```javascript
import { 
  attachClassifierMethods, 
  attachInstanceMethodsAndListeners,
  SYMBOL_BASE_URL,
  SYMBOL_AUTH 
} from '@schematize/client-jsonapi';
import { resurrect } from '@schematize/metamodel';

// Load your UML metamodel
const package = await resurrect(metamodelJson);

// Attach JSON:API methods to classifiers
attachClassifierMethods({ package });

// Attach instance methods and event listeners
attachInstanceMethodsAndListeners();

// Configure base URL for a classifier
UserClass[SYMBOL_BASE_URL] = 'https://api.example.com';

// Configure authentication (optional)
UserClass[SYMBOL_AUTH] = authProvider;
```

### Finding Instances

```javascript
// Find all users
const users = await UserClass.find({
  filter: {
    symbol: '&&',
    operand: [
      {
        language: ['SQL'],
        body: ['status = "active"']
      }
    ]
  },
  include: ['posts', 'profile'],
  fields: {
    'User': ['name', 'email'],
    'Post': ['title', 'content']
  }
});

// Find user by ID
const user = await UserClass.findById({
  __id__: 'user123',
  include: ['posts', 'posts.comments']
});

// Find related instances
const userPosts = await user.findRelated({
  propertyName: 'posts',
  filter: {
    language: ['SQL'],
    body: ['published = true']
  }
});
```

### Saving Instances

```javascript
// Create new user
const user = new UserClass({
  name: 'John Doe',
  email: 'john@example.com'
});

// Save to server
await user.save();

// Update existing user
user.name = 'Jane Doe';
await user.save(); // Only sends changed attributes
```

### Lazy Loading

```javascript
// Load property on demand
const posts = await user.$('posts');

// Force reload (bypass cache)
const freshPosts = await user.$('posts', { force: true });
```

### Link Management

The library provides advanced link management with automatic tracking and cleanup:

```javascript
// Commit added links
await user.commitLinksChanged({
  associationEnds: ['posts', 'comments']
});

// Commit removed links
await user.commitLinksRemoved({
  associationEnds: ['oldPosts']
});
```

**Enhanced Features:**
- Automatic bidirectional link synchronization
- Support for complex association hierarchies
- Event notifications: Fires `jsonapi:change` events when links are committed

## API Reference

### Core Functions

#### attachClassifierMethods

Attaches `find` and `findById` methods to UML classifiers.

**Parameters:**
- `package` (Object): UML package containing classifiers

**Usage:**
```javascript
attachClassifierMethods({ package });
```

#### attachInstanceMethodsAndListeners

Attaches instance methods and sets up event listeners for change tracking.

**Usage:**
```javascript
attachInstanceMethodsAndListeners();
```

### Instance Methods

#### find

Finds instances of a classifier with optional filtering, includes, and field selection.

**Parameters:**
- `__type__` (Object): UML classifier (defaults to `this`)
- `fields` (Object): Field selection by type (JSON:API sparse fieldsets)
- `filter` (Object): Filter conditions using symbol/operand format
- `include` (Array): Related data to include (JSON:API includes)

**Returns:**
- `Promise<Array>`: Array of found instances

**Usage:**
```javascript
const instances = await UserClass.find({
  filter: {
    symbol: '&&',
    operand: [
      {
        language: ['SQL'],
        body: ['age >= 18']
      }
    ]
  },
  include: ['posts', 'profile'],
  fields: {
    'User': ['name', 'email'],
    'Post': ['title']
  }
});
```

#### findById

Finds a single instance by its ID.

**Parameters:**
- `__type__` (Object): UML classifier (defaults to `this`)
- `__id__` (String): Instance ID to find
- `fields` (Object): Field selection by type
- `filter` (Object): Additional filter conditions
- `include` (Array): Related data to include

**Returns:**
- `Promise<Object>`: Found instance or undefined

**Usage:**
```javascript
const user = await UserClass.findById({
  __id__: 'user123',
  include: ['posts', 'posts.comments'],
  fields: {
    'User': ['name', 'email'],
    'Post': ['title', 'content']
  }
});
```

#### save

Saves an instance to the server, handling both creates and updates.

**Parameters:**
- `instance` (Object): Instance to save (defaults to `this`)
- `skipCompositeProperties` (Boolean): Skip saving composite properties.  When true, composite properties (owned relationships) will not be automatically saved during the save operation.  Useful when you want to handle composite saves manually or in a different order.  Default's to false.
- `skipStructuralValues` (Boolean): Skip saving structural values.  When true, structured values (complex objects that are part of the instance) will not be automatically saved.  Use this when you want to handle structured value saves separately.  Default's to false.
- `commitLinksChanged` (Boolean|Object): Commit added links to the server.  When true, commits all added association links.  When an object, should contain `associationEnds` array specifying which association ends to commit.  Links are committed via POST requests to the relationships endpoint.
- `commitLinksRemoved` (Boolean|Object): Commit removed links to the server.  When true, commits all removed association links.  When an object, should contain `associationEnds` array specifying which association ends to commit.  Links are committed via DELETE requests to the relationships endpoint.
- `parametersProvider` (Function): Optional function that provides additional parameters for cascading save operations.  When provided, this function is called for each nested instance being saved (e.g., structured values, composite properties) and should return an object with additional save parameters.  Useful for dynamically configuring save behavior for nested instances.  **Either/or:** If you pass `parametersProvider`, it overrides any values you passed directly for `skipCompositeProperties`, `skipStructuralValues`, `commitLinksChanged`, and `commitLinksRemoved`... use direct parameters or `parametersProvider` for those options, not both.

**Returns:**
- `Promise<void>`

**Usage:**
```javascript

// Listen for changes saved
user.on('jsonapi:change', (event) => {
  if (event.detail.type === 'saved') {
    console.log('Successfully saved with authentication');
  }
});

// save
await user.save({
  commitLinksChanged: true,
  commitLinksRemoved: {
    associationEnds: ['oldPosts']
  },
  parametersProvider: ({ instance }) => ({
    // Provide additional parameters for nested saves
    commitLinksChanged: true,
    commitLinksRemoved: true
  })
});
```

**Features:**
- **Change Tracking**: Only sends modified attributes
- **Cascading Saves**: Automatically saves composite properties
- **Link Management**: Handles association links and structured values
- **Event Dispatching**: Fires `jsonapi:change` events with `type: 'saved'` on successful save
- **Authentication**: Automatic OAuth token handling

#### delete

Deletes an instance from the server.

**Parameters:**
- `instance` (Object): Instance to delete (defaults to `this`)

**Returns:**
- `Promise<void>`

**Usage:**
```javascript
await user.delete();
```

#### $

Lazy loads a property value from the server.

**Parameters:**
- `instance` (Object): Instance to load property for (defaults to `this`)
- `propertyName` (String): Name of property to load
- `force` (Boolean): Force reload, bypassing cache (default: false)

**Returns:**
- `Promise<any>`: Property value

**Usage:**
```javascript
// Load posts property
const posts = await user.$('posts');

// Force reload
const freshPosts = await user.$('posts', { force: true });
```

**Features:**
- **Caching**: Properties are cached for 60 seconds
- **Promise-based**: Returns promises to prevent duplicate requests
- **Collection Handling**: Properly manages array properties
- **Change Integration**: Integrates with change tracking system

#### needsSave

Checks if an instance has unsaved changes and needs to be saved to the server.

**Parameters:**
- `instance` (Object): Instance to check (defaults to `this`)

**Returns:**
- `Boolean`: `true` if the instance needs to be saved, `false` otherwise

**Usage:**
```javascript
const user = new UserClass({ name: 'John' });
console.log(user.needsSave()); // true (new instance)

await user.save();
console.log(user.needsSave()); // false (clean instance)

user.name = 'Jane';
console.log(user.needsSave()); // true (has changes)
```

**What triggers needsSave:**
- **New instances**: Instances that haven't been saved yet
- **Changed attributes**: Modified primitive properties or enumerations
- **Structured values**: Added, changed, or removed composite properties
- **Association links**: Added or removed association relationships

**Features:**
- **Automatic tracking**: No manual intervention required
- **Comprehensive detection**: Covers all types of changes
- **Performance optimized**: Quick boolean check without side effects
- **Event integration**: Triggers `jsonapi:change` events with `type: 'unclean'` when changes are detected

#### findRelated

Finds instances related to this instance through a specific property.

**Parameters:**
- `instance` (Object): Source instance (defaults to `this`)
- `__type__` (Object): Instance type (auto-detected)
- `propertyName` (String): Property name to follow
- `fields` (Object): Field selection by type
- `filter` (Object): Additional filter conditions
- `include` (Array): Related data to include

**Returns:**
- `Promise<Object|Array>`: Related instance(s)

**Usage:**
```javascript
const userPosts = await user.findRelated({
  propertyName: 'posts',
  filter: {
    language: ['SQL'],
    body: ['published = true']
  },
  include: ['comments']
});
```

#### findLinks

Finds association links from an instance.

**Parameters:**
- `instance` (Object): Source instance (defaults to `this`)
- `associationEnds` (Array): Association end names to search

**Returns:**
- `Promise<Array>`: Array of association links

**Usage:**
```javascript
const links = await user.findLinks({
  associationEnds: ['userRoles', 'userGroups']
});
```

#### commitLinksChanged

Commits added association links to the server.

**Parameters:**
- `instance` (Object): Source instance (defaults to `this`)
- `associationEnds` (Array): Association end names to commit

**Returns:**
- `Promise<Array>`: Array of commit promises

**Usage:**
```javascript
await user.commitLinksChanged({
  associationEnds: ['posts', 'comments']
});
```

#### commitLinksRemoved

Commits removed association links to the server.

**Parameters:**
- `instance` (Object): Source instance (defaults to `this`)
- `associationEnds` (Array): Association end names to commit

**Returns:**
- `Promise<Array>`: Array of commit promises

**Usage:**
```javascript
await user.commitLinksRemoved({
  associationEnds: ['oldPosts']
});
```

### Symbols

#### SYMBOL_BASE_URL

Symbol for configuring the base URL for JSON:API endpoints.

**Usage:**
```javascript
UserClass[SYMBOL_BASE_URL] = 'https://api.example.com';
```

#### SYMBOL_AUTH

Symbol for configuring authentication provider.

**Usage:**
```javascript
UserClass[SYMBOL_AUTH] = authProvider;
```

#### SYMBOL_NEW

Internal symbol tracking whether an instance is new (not yet saved).

#### SYMBOL_ATTRIBUTES

Internal symbol storing changed attributes.

#### SYMBOL_LINKS_CHANGED

Internal symbol tracking changed association links.

#### SYMBOL_LINKS_REMOVED

Internal symbol tracking removed association links.

#### SYMBOL_LINK

Internal symbol used to store link references in resource objects.

#### SYMBOL_STRUCTURED_VALUES_CHANGED

Internal symbol tracking changed structured values.

#### SYMBOL_STRUCTURED_VALUES_REMOVED

Internal symbol tracking removed structured values.

#### SYMBOL_OWNER

Internal symbol storing owner information for composite instances.

#### SYMBOL_PROPERTY_EXPIRES

Internal symbol tracking property cache expiration times.

#### SYMBOL_UNLINKED

Internal symbol tracking whether an instance has been unlinked from an association.

#### SYMBOL_DESTROYED

Internal symbol tracking whether an instance has been destroyed.

### Constants

#### JSONAPI_CONTENT_TYPE

The JSON:API content type header value: `application/vnd.api+json`

#### EXPIRES

Default cache expiration time in milliseconds (60 seconds by default): `60000`

#### OWNING_INSTANCE

Constant string (`schematize:__owningInstance__`) used to identify the owning instance in resource identifiers for structured values.

#### OWNING_PROPERTY

Constant string (`schematize:__owningProperty__`) used to identify the owning property in resource identifiers for structured values.

#### OWNING_TYPE

Constant string (`schematize:__owningType__`) used to identify the owning type in resource identifiers for structured values.

### Event System

The library provides a comprehensive event system for tracking instance changes:

#### Instance Events

- **`change`**: Fired when instance properties change
- **`jsonapi:change`**: Fired for JSON:API specific changes
  - `type: 'unclean'`: Instance marked as dirty
  - `type: 'saved'`: Instance successfully saved
- **`instance`**: Fired when new instances are created
- **`destroy`**: Fired when instances are destroyed
- **`get`**: Fired when properties are accessed

#### Collection Events

- **`change`**: Fired when collection items are added/removed

**Usage:**
```javascript
// Listen to instance changes
user.on('change', (event) => {
  console.log('Instance changed:', event.detail);
});

// Listen to save events
user.on('jsonapi:change', (event) => {
  if (event.detail.type === 'saved') {
    console.log('Instance saved successfully');
  }
});
```

## Advanced Features

### Change Tracking

The library automatically tracks changes to instances:

```javascript
const user = new UserClass({ name: 'John' });
console.log(user.needsSave()); // true (new instance)

await user.save(); // Initial save
console.log(user.needsSave()); // false (clean)

user.name = 'Jane'; // Automatically marked as dirty
console.log(user.needsSave()); // true (has changes)
await user.save(); // Only sends the changed 'name' attribute
```

**Change Detection:**
The `needsSave()` method checks for:
- New instances that haven't been saved
- Modified primitive attributes and enumerations
- Added, changed, or removed structured values
- Added or removed association links

This enables efficient saving by only sending changed data to the server.

**Event Integration:**
```javascript
// Listen for change events
user.on('jsonapi:change', (event) => {
  if (event.detail.type === 'unclean') {
    console.log('Instance has unsaved changes');
  } else if (event.detail.type === 'saved') {
    console.log('Instance saved successfully');
  }
});
```

### Composite Properties

Handles composite (owned) properties with automatic cascading:

```javascript
const user = new UserClass({ name: 'John' });
const profile = new ProfileClass({ bio: 'Developer' });

user.profile = profile; // Composite relationship
await user.save(); // Automatically saves profile too
```

### Lazy Loading with Caching

Properties are loaded on-demand and cached:

```javascript
// First access - loads from server
const posts = await user.$('posts');

// Subsequent access - uses cache (within 60 seconds)
const cachedPosts = await user.$('posts');

// Force reload - bypasses cache
const freshPosts = await user.$('posts', { force: true });
```

### Authentication Integration

Automatic OAuth token handling:

```javascript
// Configure authentication
UserClass[SYMBOL_AUTH] = authProvider;

// All requests automatically include authorization headers
const users = await UserClass.find();
```

### JSON:API Features

Major features of JSON:API specification supported:

```javascript
// Sparse fieldsets
const users = await UserClass.find({
  fields: {
    'User': ['name', 'email'],
    'Post': ['title']
  }
});

// Includes
const user = await UserClass.findById({
  __id__: '123',
  include: ['posts', 'posts.comments']
});

// Filtering
const users = await UserClass.find({
  filter: {
    symbol: '&&',
    operand: [
      {
        language: ['SQL'],
        body: ['age >= 18']
      }
    ]
  }
});
```

### Cross-Platform Support

Works in both browser and Node.js environments:

```javascript
// Automatically detects environment and uses appropriate HTTP client
// Browser: Uses fetch API
// Node.js: Uses https module
const users = await UserClass.find();
```

## Error Handling

The library provides comprehensive error handling with automatic retry for authentication:

```javascript
try {
  const user = await UserClass.findById({ __id__: 'nonexistent' });
} catch (error) {
  console.error('Error:', error.message);
  // Automatic 401 handling with auth retry
}
```

## Performance Considerations

- **Lazy Loading**: Properties are only loaded when accessed
- **Change Tracking**: Only modified attributes are sent
- **Caching**: Properties are cached for 60 seconds by default
- **Batch Operations**: Multiple saves are batched when possible

## License

MIT

## Author

Benjamin Bytheway