pinpodev/time-slots-finder

An API to find available time slots in a calendar.

time-slots-finder's Issues

Incorrect iCal parsing

When parsing public google iCal files (for bank holidays). The library didn't produce any slots.

To Reproduce
Use https://calendar.google.com/calendar/ical/cs.czech%23holiday%40group.v.calendar.google.com/public/basic.ics as calendarData
No slots for any configuration gets generated as the iCal parser doesn't return any events as a result of extraction.

Expected behavior
Should return few tens of events.

Additional context
Fix is pretty straightforward in this case, but I think due to the naivity of the parser there are going to be much more edge cases.

Core problem is with the end key detection - correct way would be something as

var endDateKey = eventTimeZone ? "DTEND;TZID=" + eventTimeZone : keys.find(function (key) { return key.startsWith("DTEND"); });
if (!endDateKey) {
  return null;
}

because for full day events the date string doesn't contain 15 characters but only 8 the function _parseICalDate also fails to properly parse the input date.

For me moving forward it seems to be better with just parsing the iCal myself (and leveraging caching and other optimizations in the process) and filling the events into unavailablePeriods config.
For the community to be actually able to use this lib properly it is only missing a way to introduce custom extractor so anybody can tweak the ical extractor to their case.

Anyway the slot generation logic works fell so far, good job! :)

Incorrect documentation or bug in code regarding skipping hour/minutes in unavailableTimes aka all day events

Hi there, just a small thing :)

Readme states that:

• Objet containing at least month and day values.
• If years are ommited, event repeat every years.
• If hour are ommited, all day is included: hour 00:00 is used for startAt and 23:59 is used for
• endAt.

The second part doesnt behave like this, you also need to skip the year for you to be able to skip hour and minutes, else you get TimeSlotsFinderError: Unavailable period nº1 is invalid error

I can see this case is not covered in scenarios, so cant tell if its bug or feature and just the docs are wrong :)

p.s.: I hope I will get to the other reports soon, hopefully during holiday so I dont just find bugs but actually help fix them too :D

Errata in documentation about `minTimeBeforeFirstSlot` option

Describe the bug
The description indicates that the unit used for the minTimeBeforeFirstSlot option is hours, but in reality it is minutes.

Expected behavior
The documentation should be corrected to indicate the correct unit for this option.

Basic Improvements

Fix README:

• Usage: fix typos in comment
• timeSlotDuration: "The lengths of the time slots in minutes. " => "The length"
• unworkedPeriods: "If the year is specified for one of the date, it MUST BE defined for the other." => "A same unworked period must have the same date format for both startDate and endDate"
• minAvailableTimeBeforeSlot: "The minimum amount of minutes available before a slot." => "The minimum number of free minutes required before a slot."
• minAvailableTimeAfterSlot: "The minimum amount of minutes available after a slot." => "The minimum number of free minutes required after a slot."
• Advanced usage: "If you want to check that a configuration is valid without running a search, we provide a function to do it." => "If you want to check that a configuration is valid without running a search, you can use the isConfigurationValid function as follows:"

Add some clarity comments in:

• while loop in getAvailableTimeSlotsInCalendar
• while loop in _getAvailableTimeSlotsForShift

Fix some var names:

• workedPeriods => availablePeriods ? (IMO it has nothing to do with work, but rather with availability)
• unworkedPeriods => unavailablePeriods

Code consistency:

• Use minutes as duration unit for minTimeBeforeFirstSlot (same unit as minAvailableTimeBeforeSlot and minAvailableTimeAfterSlot)

Unable to use the unavailablePeriods

This code breaks

let TimeSlotsFinder=require("time-slots-finder");

const slots = TimeSlotsFinder.getAvailableTimeSlotsInCalendar({
    calendarData: "",
    calendarFormat: TimeSlotsFinder.TimeSlotsFinderCalendarFormat.iCal,
    configuration: {
        timeSlotDuration: 60,
        minAvailableTimeBeforeSlot: 15,
        minTimeBeforeFirstSlot: 24 * 60, // 48 hours in minutes
        availablePeriods: [{
            isoWeekDay: 5,
            shifts: [{ startTime: "10:00", endTime: "12:30" }] 
        }, {
            isoWeekDay: 6,
            shifts: [
                { startTime: "10:00", endTime: "20:00" },
                { startTime: "10:00", endTime: "13:00" },
            ]
        }],
        unavailablePeriods: [{
            startAt: {year: 2021, month: 09, day: 17, hour: 11, minute: 0},
            endAt: {year: 2021, month: 09, day: 17, hour: 12, minute: 0},
        }],
        timeZone: "Asia/Kolkata",   
    },
    from: new Date("2021-09-12T00:00:00.000+05:30"),
    to: new Date("2021-10-13T23:59:59.999+05:30"),
});
console.log(slots);

Error:

TimeSlotsFinderError: Unavailable period nº1 is invalid
at new TimeSlotsFinderError (/home/runner/TimelySereneIde/node_modules/time-slots-finder/lib/errors.js:22:28)
at Object.isConfigurationValid (/home/runner/TimelySereneIde/node_modules/time-slots-finder/lib/config-management.js:53:23)
at _checkSearchParameters (/home/runner/TimelySereneIde/node_modules/time-slots-finder/lib/time-slots.js:84:25)
at Object.getAvailableTimeSlotsInCalendar (/home/runner/TimelySereneIde/node_modules/time-slots-finder/lib/time-slots.js:38:22)
at /home/runner/TimelySereneIde/index.js:3:31
at Script.runInContext (vm.js:130:18)
at Object. (/run_dir/interp.js:209:20)
at Module._compile (internal/modules/cjs/loader.js:999:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1027:10)
at Module.load (internal/modules/cjs/loader.js:863:32)

Add enhancements to periods configuration

The purpose of this issue is to add a timeSlotRecurringTime param in configuration.
This will tell us how to determine slots based on this.

Exemple:

    configuration: {
        timeSlotDuration: 15,
        timeSlotRecurringTime: 20, // minutes
        minAvailableTimeBeforeSlot: 5,
        workedPeriods: [{
            isoWeekDay: 5,
            shifts: [{ startTime: "08:00", endTime: "12:00" }] 
        }],
        timeZone: "Europe/Paris",   
    }

This means that each slot can only start every 20 minutes after startTime, meaning that the configuration above would return slots like:

[
	{
		"startAt": "2020-10-22T08:00:00.000Z",
		"endAt": "2020-10-22T08:15:00.000Z",
		"duration": 15
	},
	{
		"startAt": "2020-10-22T08:20:00.000Z",
		"endAt": "2020-10-22T08:35:00.000Z",
		"duration": 15
	},
	{
		"startAt": "2020-10-22T08:40:00.000Z",
		"endAt": "2020-10-22T08:55:00.000Z",
		"duration": 15
	},
	{
		...
	}
]

Minutes booked per date

Firstly thanks for this super useful library!

It would be handy if the plugin could return an array of dates for each day that contains a count of minutes that are either available or unavailable (whichever makes most sense for your library).

This allows for easy overall availability reporting, for example if you wanted to show a traffic light colouring system on each day of a calendar to indicate how busy it was.

{
  slots: [],
  slotsSummary: [
   '2022-10-08': 300,
    '2022-10-09': 0
  ]
}

Incoming daylight saving time change

When generating slots for Sunday Oct 31st, something wonky is happening, I get 1 hour less of slots then I am supposed to get.

To Reproduce
Generate slots for Sunday Oct 31st, (I am doing 8-12 AM, with slots length 30 => 8 slots)
Generator calculates only 6 slots (2 last from the end of range are missing)

I am still investigating this issue, I might send a fix, so this is more of a FYI, gien the issue wont survive this weekend and we have another half a year before this begins to be nuissance :D

Incorrect time slot start based on "from" ending in previous day or starting in the one where you generate slots

with config like this:

getAvailableTimeSlotsInCalendar({
      configuration: {
        unavailablePeriods: [],
        timeSlotDuration: 30,
        minAvailableTimeBeforeSlot: 0,
        minTimeBeforeFirstSlot: 0,
        availablePeriods: [{ isoWeekDay: 3, shifts: [{ startTime: '08:00', endTime: '12:00' }] }],
        timeZone: 'Europe/Prague',
        slotStartMinuteStep: 1
      },
      from: new Date('2022-03-02T00:00:00.000Z'),
      to: new Date('2022-03-08T23:59:59.999Z')
    })

you get result where first slot starts correctly at startAt: 2022-03-02T07:00:00.000Z

but if the from is set to end of previous day 2022-03-01T23:59:59.999Z then the slot for some reason starts at startAt: 2022-03-02T07:01:00.000Z - the one minute causes that you then end up with one less slot then you should have