StudyMate Smart Planner

A lightweight, dependency-free JavaScript package that helps student apps prioritize assignments, understand deadlines, break large tasks into manageable steps, and track progress. All recommendations use transparent rules and calculations; no AI API or network connection is required.

Features

• Smart priority score (0–100): combines deadline urgency, task importance, and estimated effort.
• Deadline intelligence: labels tasks as overdue, due-today, urgent, soon, or upcoming.
• Anti-procrastination breakdown: generates six actionable steps for a large assignment.
• Progress analytics: calculates completed, remaining, and percentage complete.
• Study summary: combines progress, deadline counts, and the highest-priority unfinished task.
• No dependencies: uses native JavaScript and Node.js built-in testing tools.

Requirements

Node.js 18 or newer.

Install

After publishing, install with:

npm install studymate-smart-planner

Quick start

import {
  prioritizeTasks,
  breakDownAssignment,
  getProgress,
  getStudySummary
} from 'studymate-smart-planner';

const tasks = [
  {
    title: 'Software Engineering report',
    dueDate: '2026-11-02',
    importance: 5,       // integer from 1 (low) to 5 (high)
    estimatedHours: 4,
    completed: false
  },
  {
    title: 'Read Chapter 4',
    dueDate: '2026-11-06',
    importance: 2,
    estimatedHours: 1,
    completed: true
  }
];

console.log(prioritizeTasks(tasks));
console.log(breakDownAssignment({
  title: 'Software Engineering report',
  estimatedHours: 4,
  dueDate: '2026-11-02'
}));
console.log(getProgress(tasks));
console.log(getStudySummary(tasks));

For repeatable results in tests or demos, pass a fixed now date to functions that accept it.

API

getDaysRemaining(dueDate, now = new Date())

Returns the number of days until the due date. Negative values indicate an overdue deadline. Partial days are rounded up.

getDeadlineStatus(dueDate, now = new Date())

Returns one of overdue, due-today, urgent (within 2 days), soon (within 7 days), or upcoming.

calculatePriority(task, now = new Date())

Returns { score, level, daysRemaining, deadlineStatus }. Tasks need a non-empty title and valid dueDate. importance defaults to 3 and must be from 1 to 5. estimatedHours defaults to 1 and must be positive.

The score is explainable: deadline urgency contributes up to 60 points, importance up to 30 points, and estimated effort up to 10 points. This is a rule-based planning aid, not a guarantee of the objectively best study order.

prioritizeTasks(tasks, now = new Date())

Returns a new array sorted by highest priority first. It does not mutate the input array.

breakDownAssignment({ title, estimatedHours = 4, dueDate, now = new Date() })

Returns six suggested steps with estimated minutes and suggested dates. These are planning suggestions; students can adapt them to the assignment.

getProgress(tasks)

Returns { total, completed, remaining, percentage }. A task counts as completed only when completed === true.

getStudySummary(tasks, now = new Date())

Returns progress, deadline counts for unfinished tasks, and the highest-priority unfinished task (or null if there are no unfinished tasks).

Validate locally

npm test
npm run demo
npm pack --dry-run

Publish to npm

1. Create or sign in to your npm account at https://www.npmjs.com/.
2. In the project folder, run npm login and complete any verification requested by npm.
3. Check whether the name is available: npm view studymate-smart-planner.
4. Run npm test and npm pack --dry-run.
5. Publish with npm publish.
6. Verify the package page at https://www.npmjs.com/package/studymate-smart-planner.

If the name is already taken, choose an available name (for example, a distinctive name that includes your npm username) and update the name field in package.json before publishing. Do not publish until you have reviewed the package contents and confirmed the name.

Author

H.jameel

License

Proprietary — all rights reserved. No permission is granted to copy, modify, or redistribute this package without prior written permission. See LICENSE.

Publishing note: publishing a package publicly on npm makes its published files available for people to download and inspect. This proprietary notice does not hide the source code or technically prevent copying. Confirm your assignment's public publication requirement before running npm publish.