@skedulo/pulse-solutions-framework

Data Service

A comprehensive TypeScript service library for GraphQL-based data operations with support for complex object relationships, batch processing, and advanced querying capabilities.

Features

• Dynamic Query Building: Automatically generates GraphQL queries based on object definitions
• Relationship Handling: Supports nested references and related lists with configurable depth levels
• Batch Processing: Efficiently handles large datasets with automatic chunking
• Change Detection: Only sends modified fields during updates to optimize performance
• Pagination Support: Automatic handling of paginated results
• Flexible Filtering: Support for various operators and custom conditions

Installation

npm install @skedulo/pulse-solutions-framework

Object Definition

import { createObjectDefinition, MappingType, ObjectDefinition } from '@skedulo/pulse-solutions-framework'

export const JobsDefinition: ObjectDefinition = createObjectDefinition({
  objectName: 'Jobs',
  fieldConfigs: [
    { fieldName: 'UID' }, //mappingType: MappingType.string as default
    { fieldName: 'Name', readonly: true },
    { fieldName: 'Account', mappingType: MappingType.reference, referenceObject: 'Accounts' },
    {
      fieldName: 'JobAllocations',
      mappingType: MappingType.relatedList,
      referenceObject: 'JobAllocations',
      parentField: 'Job'
    },
    { fieldName: 'JobAllocationTimeSource', mappingType: MappingType.boolean },
    { fieldName: 'Quantity', mappingType: MappingType.number },
    { fieldName: 'Start', mappingType: MappingType.datetime }
  ]
})

Configuration

Service Settings

Property	Type	Default	Description
objectName	string	Required	Name of the primary object
objectDefinitions	Record<string, ObjectDefinition>	Required	Collection of object definitions

Basic Usage

Creating a Service Instance

import { createBaseService, ServiceSetting } from '@skedulo/pulse-solutions-framework'
import * as objectDefinitions from './my-object-definitions'

interface Jobs extends BaseModel {
  AccountId: string
  JobStatus: string
  // ... other fields
}

const settings: ServiceSetting = {
  objectName: 'Jobs',
  objectDefinitions: objectDefinitions
}

const jobsService = createBaseService<Jobs>(settings)

Querying Data

import { QueryModel, Operator } from '@skedulo/pulse-solutions-framework'

// Simple query
const queryModels: QueryModel[] = [
  {
    conditions: [
      ['AccountId', Operator.EQUAL, 'account-uid'],
      ['JobStatus', Operator.NOT_IN, ['Cancelled']]
    ],
    orderBy: 'CreatedDate DESC'
  }
]

const result = await jobsService.query(queryModels)

Saving Data

// Insert records
const recordsToInsert: Jobs[] = [
  { AccountId: 'account-uid-1', JobStatus: 'Queued' },
  { AccountId: 'account-uid-2', JobStatus: 'Queued' }
]

// Update records
const recordsToUpdate: Jobs[] = [{ UID: 'existing-id', AccountId: 'account-uid', JobStatus: 'Pending Dispatch' }]

// Delete records
const recordsToDelete: Jobs[] = [{ UID: 'existing-id', _IsDeleted: true }]

await jobsService.save([...recordsToInsert, ...recordsToUpdate, ...recordsToDelete])

Advanced Usage

Complex Queries with Custom Logic

const complexQuery: QueryModel[] = [
  {
    conditions: [
      ['Start', Operator.GREATER_OR_EQUAL, '2025-01-01T00:00:00.000Z'],
      ['End', Operator.LESS_OR_EQUAL, '2025-12-31T00:00:00.000Z'],
      ['JobStatus', Operator.IN, ['Pending Allocation', 'Pending Dispatch']]
    ],
    customLogic: '(1 AND 2) AND 3', // Reference conditions by index
    orderBy: 'CreatedDate DESC'
  }
]

Period-based Queries

const periodQuery: QueryModel[] = [
  {
    conditions: [[['Start', 'End'], Operator.PERIOD, ['2025-01-01T00:00:00.000Z', '2025-12-31T00:00:00.000Z']]]
  }
]

Custom Conditions

const customQuery: QueryModel[] = [
  {
    conditions: [['my_custom_query', Operator.CUSTOM, 'ContactId != null AND ContactId != ""']]
  }
]

Related List Queries

const jobsWithJobAllocationsQuery: QueryModel[] = [
  {
    conditions: [['JobStatus', Operator.NOT_IN, ['Cancelled']]],
    orderBy: 'CreatedDate DESC'
  },
  {
    relatedList: 'JobAllocations',
    conditions: [['Status', Operator.NOT_IN, ['Deleted', 'Declined']]]
  }
]

Query Options

const options: QueryOptions = {
  readOnly: true // Optimize for read-only operations
}

const result = await jobsService.query(queryModels, options)

Save Options

const options: SaveOptions = {
  sourceRecords: [], // Original records for change detection
  bulkOperation: true, // Enable bulk operation mode
  suppressChangeEvents: true // Suppress change events
}

const result = await jobsService.save(records, options)

Supported Operators

Operator	GraphQL Equivalent	Description
EQUAL	==	Equality comparison
NOT_EQUAL	!=	Inequality comparison
IN	IN	Value in array
NOT_IN	NOTIN	Value not in array
GREATER	>	Greater than
GREATER_OR_EQUAL	>=	Greater than or equal
LESS	<	Less than
LESS_OR_EQUAL	<=	Less than or equal
INCLUDES	INCLUDES	String value included
EXCLUDES	EXCLUDES	String value excluded
INCLUDES_ALL	Custom	All string values included
INCLUDES_ANY	Custom	Any string included
EXCLUDES_ALL	Custom	All string values excluded
PERIOD	Custom	Date range overlap
PERIOD_INCLUDE_NULL	Custom	Date range overlap including records have period fields value is null
CUSTOM	Custom	Raw GraphQL condition

API Reference

DataService Interface

interface DataService<T extends BaseModel> {
  newQueryBuilder(queryModels: QueryModel[]): GraphQLQueryBuilder
  query(queryModels: QueryModel[], options?: QueryOptions): Promise<GetListResponse<T>>
  save(objects: T[], options?: SaveOptions<T>): Promise<SaveResult[]>
}

QueryModel

interface QueryModel {
  conditions?: [string | string[], Operator, any][]
  customLogic?: string
  orderBy?: string
  limit?: number
  relatedList?: string
  overriddenFields?: string
}

Performance Considerations

• Batch Processing: Large datasets are automatically chunked to respect API limits
• Change Detection: Only modified fields are sent during updates
• Circular Reference Prevention: Automatic detection and prevention of circular lookups
• Pagination: Automatic handling of large result sets
• Field Selection: Only predefined fields are queried based on object definitions

Best Practices

• Use Change Detection: Provide sourceRecords for optimal update performance
• Batch Operations: Consider bulkOperation: true for large datasets. This helps optimize large-scale mutations
• Suppress Change Events: Consider suppressChangeEvents: true for large datasets. This disables change history tracking, helping to minimize delays.

Recurring Service

The recurring-service module provides utilities for generating recurring dates based on customizable patterns. It supports daily, weekly, monthly, and yearly recurrence rules with advanced options like skipping specific dates, handling timezones, and limiting occurrences.

Features

• Flexible Recurrence Rules: Supports daily, weekly, monthly, and yearly recurrence modes.
• Advanced Options:
  • Skip specific dates or weekdays.
  • Define end conditions (after a number of occurrences or on a specific date).
  • Handle leap years and months with fewer days.
• Timezone Support: Generate dates in specific timezones using luxon.
• Type Safety: Fully typed with TypeScript for robust development.

Generators

The following generators are available for creating recurring dates:

• Daily Generator: daily-generator.ts
• Weekly Generator: weekly-generator.ts
• Monthly Generator: monthly-generator.ts
• Yearly Generator: yearly-generator.ts

Each generator implements the RecurringGenerator interface and provides the following methods:

• generateDates(pattern: RecurringPattern): DateTime[]
• getRepeatMode(): RepeatMode

Types

The module defines the following key types in types.ts:

• RecurringPattern: Configuration object for defining recurrence rules.
• RecurringGenerator: Interface for generators.

Usage

Example: Daily Recurrence

import { dailyRecurringGenerator } from './generators/daily-generator'
import { RepeatMode, EndMode, RecurringPattern } from './types'

const generator = dailyRecurringGenerator()

const pattern: RecurringPattern = {
  startDate: '2024-01-01',
  timezoneSidId: 'UTC',
  repeatMode: RepeatMode.Daily,
  every: 1,
  endMode: EndMode.After,
  endAfterNumberOccurrences: 5
}

const dates = generator.generateDates(pattern)
console.log(dates.map(date => date.toISODate()))
// Output: ['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04', '2024-01-05']

Example: Monthly Recurrence with Skipped Dates

import { monthlyRecurringGenerator } from './generators/monthly-generator'
import { RepeatMode, EndMode, RecurringPattern } from './types'

const generator = monthlyRecurringGenerator()

const pattern: RecurringPattern = {
  startDate: '2024-01-15',
  timezoneSidId: 'UTC',
  repeatMode: RepeatMode.Monthly,
  every: 1,
  endMode: EndMode.After,
  endAfterNumberOccurrences: 3,
  repeatOnDayOfMonth: 15,
  skippedDates: ['2024-02-15']
}

const dates = generator.generateDates(pattern)
console.log(dates.map(date => date.toISODate()))
// Output: ['2024-01-15', '2024-03-15', '2024-04-15']

Example: Yearly Recurrence with Leap Year Handling

import { yearlyRecurringGenerator } from './generators/yearly-generator'
import { RepeatMode, EndMode, RecurringPattern } from './types'

const generator = yearlyRecurringGenerator()

const pattern: RecurringPattern = {
  startDate: '2024-02-29',
  timezoneSidId: 'UTC',
  repeatMode: RepeatMode.Yearly,
  every: 1,
  endMode: EndMode.After,
  endAfterNumberOccurrences: 2
}

const dates = generator.generateDates(pattern)
console.log(dates.map(date => date.toISODate()))
// Output: ['2024-02-29', '2025-02-28']

Testing

Unit tests for the recurring service are located in the unit-test/recurring-service folder. Each generator and helper function is thoroughly tested with various edge cases.

File Structure

• base-service.ts: Core service for generating recurring dates and summaries.
• helper.ts: Utility functions for validating and preprocessing patterns.
• types.ts: Type definitions and enums for recurring patterns.
• generators/: Contains the daily, weekly, monthly, and yearly generators.

Template Service

The template-service module provides a flexible and extensible system for applying configuration templates to objects. It supports dynamic field processing, custom field handlers, and object-specific template engines with caching for optimal performance.

Features

• Dynamic Template Processing: Apply configuration templates to objects with customizable field handlers
• Object-Specific Engines: Create specialized template engines for different object types
• Field Handler Registry: Register custom field processors for specific object types and fields
• Template Caching: Efficient caching system for templates
• Extensible Architecture: Easy to extend with new object types and field handlers

Usage

Basic Template Service

import { createTemplateService } from './base-service'

const templateService = createTemplateService()

// Register custom field handlers
templateService.registerObjectFieldHandlers('MyObject', {
  customField: (fieldValue, targetObject) => {
    targetObject.customField = fieldValue.toUpperCase()
  }
})

// Create object-specific template engine
const engine = templateService.createObjectTemplateEngine('MyObject')

// Apply template to object
const myObject = { name: 'test' }
const result = await engine.applyObjectTemplate(myObject, 'myTemplate')

Job Template Service

import { createJobTemplateService } from './job-template-service'

const jobTemplateService = createJobTemplateService()

// Generate job from template
const job = {
  Name: 'Installation Job',
  Start: '2024-01-01T09:00:00.000Z',
  Timezone: 'UTC'
}

const jobWithTemplate = await jobTemplateService.generateJobByTemplate(
  job,
  'InstallationTemplate',
  false // multipleRequirementEnabled
)

Job-Specific Features

Duration Handling

Automatically calculates job end time based on duration:

// Template field: Duration = 120 (minutes)
// Input job with Start time
const job = {
  Start: '2024-01-01T09:00:00.000Z',
  Timezone: 'UTC'
}

// Result will include calculated End time
// End: '2024-01-01T11:00:00.000Z'

Job Tasks Generation

Automatically generates job tasks from template:

// Template field: JobTasks
const templateTasks = [
  { Name: 'Setup', Description: 'Initial setup' },
  { Name: 'Installation', Description: 'Main installation' }
]

// Generated JobTasks with sequence numbers
// JobTasks: [
//   { Name: 'Setup', Description: 'Initial setup', Seq: 1 },
//   { Name: 'Installation', Description: 'Main installation', Seq: 2 }
// ]

Resource Requirements

Supports both single and multiple resource requirements:

Single Requirement Mode (default)

const job = {}
const result = await jobTemplateService.generateJobByTemplate(
  job,
  'template',
  false // single requirement mode
)

// Sets job.Quantity and job.JobTags

Multiple Requirements Mode

const job = {}
const result = await jobTemplateService.generateJobByTemplate(
  job,
  'template-name',
  true // multiple requirements mode
)

// Sets job.ResourceRequirements array

Tag Weighting

Automatically handles tag weighting and required flags:

// Template requirement with tags
const requirement = {
  qty: 2,
  tags: [
    { name: 'Electrician', tagId: 'tag-1', weighting: JobTagWeighting.Required },
    { name: 'Senior', tagId: 'tag-2', weighting: JobTagWeighting.High }
  ]
}

// Generated tags with proper Required/Weighting fields
// Tags: [
//   { TagId: 'tag-1', Required: true, Weighting: null },
//   { TagId: 'tag-2', Required: false, Weighting: 3 }
// ]

Advanced Usage

Custom Field Processors

import { FieldProcessor } from './types'

const customProcessor: FieldProcessor<MyObject> = (fieldName, fieldValue, targetObject, ...args) => {
  // Custom processing logic
  if (fieldName === 'specialField') {
    targetObject.processedField = processSpecialValue(fieldValue)
  } else {
    targetObject[fieldName] = fieldValue
  }
}

const engine = createTemplateEngine({
  fieldProcessor: customProcessor,
  additionalArgs: ['arg1', 'arg2']
})

Template Caching

The service automatically caches templates and template details for performance:

• Templates are cached by object name
• Template details are cached by objectName:templateName key
• Cache is maintained throughout the service lifecycle

Field Handler Registration

const handlers: ObjectFieldHandlers = {
  duration: (value, record) => {
    record.Duration = value
    // Additional duration processing
  },
  priority: (value, record) => {
    record.Priority = value.toUpperCase()
  }
}

templateService.registerObjectFieldHandlers('Jobs', handlers)

Performance Considerations

• Template Caching: Reduces API calls for frequently used templates
• Lazy Loading: Templates are loaded only when needed
• Efficient Field Processing: Only processes fields that aren't in the excluded list

File Structure

• base-service.ts: Base template service implementation
• job-template-service.ts: Job-specific template service extension
• types.ts: TypeScript type definitions and interfaces
• index.ts: Module exports

Contributing

When extending the template service:

• Add new field handlers to the appropriate object handlers map
• Create object-specific services for complex processing logic
• Update type definitions for new template field structures
• Add comprehensive tests for new functionality
• Follow the existing pattern of field processor functions