@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

npm install @schematize/client-jsonapi

Usage

Basic Setup

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

// 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

// Create new user
const user = new UserClass({
  name: 'John Doe',
  email: '[email protected]'
});

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

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

Lazy Loading

// 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:

// 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:

attachClassifierMethods({ package });

attachInstanceMethodsAndListeners

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

Usage:

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:

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:

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.

Returns:

• Promise<void>

Usage:

// 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:

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:

// 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:

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:

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:

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:

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:

await user.commitLinksRemoved({
  associationEnds: ['oldPosts']
});

Symbols

SYMBOL_BASE_URL

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

Usage:

UserClass[SYMBOL_BASE_URL] = 'https://api.example.com';

SYMBOL_AUTH

Symbol for configuring authentication provider.

Usage:

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:

// 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:

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:

// 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:

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:

// 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:

// 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:

// 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:

// 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:

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