PlanSolve is still in pre-alpha – Features may change or break. Feedback welcome!
Back to SDK Documentation
Try Shift Solver

JavaScript/TypeScript SDK

Official JavaScript and TypeScript SDK for the Shift Assignment Solver. Full TypeScript support with promise-based API and comprehensive error handling.

Installation

Package Installation

npm

npm install @plansolve/shift-solver

yarn

yarn add @plansolve/shift-solver

pnpm

pnpm add @plansolve/shift-solver

Basic Example

Simple Shift Assignment

import { ShiftSolver } from '@plansolve/shift-solver';

const solver = new ShiftSolver({
  apiKey: 'your-api-key-here'
});

const request = {
  name: "Hospital Shift Assignment",
  description: "Weekly shift assignment for hospital staff",
  contracts: [
    {
      name: "FULL_TIME",
      max: "PT40H",
      min: "PT32H",
      maxConsecutiveWorkDays: 5
    }
  ],
  shifts: [
    {
      name: "morning_shift",
      from: "2024-01-15T06:00:00",
      to: "2024-01-15T14:00:00",
      skills: ["nursing", "patient_care"],
      value: 3
    }
  ],
  employees: [
    {
      name: "Alice Johnson",
      contract: "FULL_TIME",
      skills: ["nursing", "patient_care", "emergency"],
      availability: ["2024-01-15"]
    }
  ]
};

try {
  const result = await solver.solve(request);
  console.log('Optimization completed:', result);
} catch (error) {
  console.error('Optimization failed:', error);
}

Advanced Examples

Skill-Based Assignment

Advanced Skills Matching
const request = {
  // ... basic setup
  shifts: [
    {
      name: "emergency_shift",
      from: "2024-01-15T22:00:00",
      to: "2024-01-16T06:00:00",
      skills: ["emergency", "critical_care"],
      value: 2,
      priority: 1
    }
  ],
  employees: [
    {
      name: "Dr. Smith",
      contract: "FULL_TIME",
      skills: ["emergency", "critical_care", "surgery"],
      availability: ["2024-01-15"],
      preference: ["emergency_shift"]
    },
    {
      name: "Nurse Johnson",
      contract: "PART_TIME",
      skills: ["nursing", "patient_care"],
      availability: ["2024-01-15"]
    }
  ],
  weights: {
    requiredSkills: 1000,
    shiftPreferences: 100,
    workloadBalance: 50
  }
};

Fairness Rules

Workload Distribution
const request = {
  // ... basic setup
  fairness: {
    fairnessBuckets: [
      {
        employees: ["Alice", "Bob", "Carol"],
        shifts: ["night_shift", "weekend_shift"],
        maxAssignments: 2
      }
    ],
    workloadDistribution: {
      targetHoursPerEmployee: 40,
      tolerance: 4
    }
  }
};

Contract Compliance

Multiple Contract Types
const request = {
  // ... basic setup
  contracts: [
    {
      name: "FULL_TIME",
      max: "PT40H",
      min: "PT32H",
      maxConsecutiveWorkDays: 5,
      maxShiftsDay: 1,
      minRestBetweenShifts: "PT11H",
      maxWorkingDays: 5
    },
    {
      name: "PART_TIME",
      max: "PT24H",
      min: "PT16H",
      maxConsecutiveWorkDays: 3,
      maxShiftsDay: 1,
      minRestBetweenShifts: "PT11H",
      maxWorkingDays: 3
    }
  ]
};

API Patterns

Async/Await vs Promises

Both Patterns Supported
// Async/await pattern
const solveAsync = async () => {
  try {
    const result = await solver.solve(request);
    return result;
  } catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      // Wait and retry
      await new Promise(resolve => setTimeout(resolve, 60000));
      return await solver.solve(request);
    }
    throw error;
  }
};

// Promise pattern
solver.solve(request)
  .then(result => {
    console.log('Success:', result);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Error Handling

Comprehensive Error Handling
try {
  const result = await solver.solve(request);
} catch (error) {
  switch (error.code) {
    case 'VALIDATION_ERROR':
      console.error('Invalid request:', error.details);
      break;
    case 'INSUFFICIENT_CREDITS':
      console.error('Not enough credits:', error.remaining);
      break;
    case 'RATE_LIMIT_EXCEEDED':
      console.error('Rate limit exceeded, retry in:', error.retryAfter);
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

TypeScript Support

Full Type Definitions

Complete TypeScript definitions for all request parameters, response types, and error objects.

IntelliSense Support

Full autocomplete and type checking in modern IDEs like VS Code, WebStorm, and others.

Generic Types

Flexible generic types for custom data structures and extended functionality.

Ready to Get Started?

Install the package and start building optimized shift assignments into your JavaScript or TypeScript application.

Quick Start GuideTry Playground