Event Days

This is a small set of classes that provide basic operations for managing calendar related data structures.

The data structures calendars, event day lists, time slots which may be within a day or across many days spanning a number of months. A time line data structure provides a relationship between a time window of months and methods use to fetch and updates monts for effective infinite scrolling.

Install

For use in node.js projects:

npm install i --save event-days

In your node.js program you can access classes in the following manner:

	const {EventDays} = require('event-days')

	let MonthContainer = EventDays.MonthContainer

Web Page Use

A rollup.config.js file has been added to the package. The npm package should be released after running npm run build. (That is best effort.)

Builds that use rollup may simply include event-days in their devDependencies field within package.json. It may help to run a second npm install a such:

npm install i --save-dev event-days

Example: This class is being used in a Svelte project. The module is included in an App.svelte file as follows:

	import {EventDays} from 'event-days'

	let MonthContainer = EventDays.MonthContainer

From there, the MonthContainer may be created and used as needed by the application.

Classes and Methods

TimeLine

With node.js

const {TimeLine} = require('event-days')

TimeSlot

A TimeSlot instance manages one labled event for any number of days. Each day is represented by a Slot object, which has three fields: 1) begin_at, end_at, and label. A time slot keeps a list of these slots where there is one slot for each day including its start time and end time and the days for the times in between. Intially, a TimeSlot is initialized with each Slot having a being_at time which is the offset of TimeSlot start time from midnight of its first day the the start of the day belonging to the Slot. Individual slots may have their times adjusted. Individual slots may be removed or added for a particulary day.

With node.js

const {TimeSlot} = require('event-days')

TimeSlotAgenda

With node.js

const {TimeSlotAgenda} = require('event-days')

MonthContainer

With node.js

const {MonthContainer} = require('event-days')

Methods

TimeLine Methods

• constructor(conf)
• async injest_month(start_time)
• async scroll_right(n)
• async scroll_left(n)
• remove_slot_everywhere(label)
• save_time_list(do_send_months)

TimeLine Constructor

Sets up the data structure for a line line. The configuration provides fields for the window size and for a number of functions which server to get and send the timeline and the month data structure. The kind of producers and consumers of the data structure is not determined. The parameters to the methods that call on them are required for operation.

Here is a list of definitions for the methods that should be supplied with the configuration.

• month_sender
• month_fetcher
• time_line_fetcher
• time_line_sender
• conflict_publisher

TimeLine injest month

Given a start time for a month, this method will either create or locate a data structure. If the month was not previously fetched, the month will be fetched with the month fetcher method.

TimeLine scrol right

Moves the window to the right (future time). If the the window size is full, the left more (least time) window will be cut out of the window list. (Note: the month data structure may still be within a map of previously fetched months depending on aging out and other space management strategies.) Every new month appearing in the window will be injested.

TimeLine scroll left

Moves the window to the left (past time). If the the window size is full, the right more (greates time) window will be cut out of the window list. (Note: the month data structure may still be within a map of previously fetched months depending on aging out and other space management strategies.) Every new month appearing in the window will be injested.

TimeLine remove slot everywhere

A time slot appearing wihin a day agenda in a month in the timeline window may be removed from the data base accessible via the configured methods. The slot will be removed in entirety. That is, given the slot has a time span greater than the timeline window, the entire span will be removed independent of what is in the window. (Note: this extent of this removal is up to the database application; however, this may be a recommendation that the database application removes the event in full.)

TimeLine save time list

The time list will be sent to any consumer of the data structures provided by this module by calling time_line_sender found in the configuration. If the parameter do_send_months is set to true, the months will be sent as well with the methods send_months.

TimeSlot Methods

• constructor(label,use_case,start_time,end_time,break_apart,importance,weekends,daily_dur)
• get_range(start_time,end_time)
• merge_with(a_time_slot)
• set_one_begining(index,a_time)
• set_one_ending(index,a_time)
• merge_with(a_time_slot)
• grow_sooner_days(num_days)
• split(start_of_split,end_of_split)
• shift_slots(delta)
• drop_by_pattern(pat_fun)
• merge_with_overlap(a_time_slot)

TimeSlot Constructor

Creates the each_day list with a Slot for each day. Each Slot will have a begin_at time which is set to the preceding midnight plus the difference between the first midnight and the start time passed to the constructor. Each Slot will have an end_at time which is the slots start time plus the constructor parameter daily_dur.

The label is determined by the application. The use_case parameter is determind by the application as well. However, a few use_cases are provided in case the application want to use them. They are the following:

• TimeSLot.USE_AS_BLOCK
• TimeSLot.USE_AS_MEET
• TimeSLot.USE_AS_ACTIVITY
• TimeSLot.USE_AS_OPEN

TimeSlot get range

Takes parameters start_time and end_time. This returns a list of slots from within the range.

TimeSlot merge with

Takes parameters start_time and end_time. This returns a list of slots from within the range.

TimeSlot set one beginning

Takes the index of the slot in the list each_day. Sets the start time, start_at, of the Slot for that index.

TimeSlot set one ending

Takes the index of the slot in the list each_day. Sets the end time, end_at, of the Slot for that index.

TimeSlot merge with

Given another time slot as a parameter, puts all the events of that time slot into the each_day list of the calling TimeSlot. If there is a space in time between then, then each day inbetween is generated with the start_at and end_\at relative times in terms of the last Slot in the each_day list of the calling slot. This discards the overlap of days, keeping the days of the calling TimeSlot.

TimeSlot grow sooner days

Prepends the list, each_day, with the copies of the first day of the list for the number of days specified in the parameter.

TimeSlot grow later days

Appends the list, each_day, with the copies of the last day of the list for the number of days specified in the parameter.

TimeSlot grow later days

Appends the list, each_day, with the copies of the last day of the list for the number of days specified in the parameter.

TimeSlot split

Splits a TimeSlot into two TimeSlots and returns them. If the times start_of_split and end_of_split, cover a spot in the middle of the TimeSlot's original expanse two new TimeSlots are returned as a pair [earlier,later]. If the times cut off the a section at the beginning, then earlier of the pair will be false. If the end is cut off, then later of the pair will be false.

TimeSlot merge with overlap

Given a TimeSlot parameter, appends all the Slots of the given TimeSlot to the calling TimeSlot and then sorst the result each_day list by start time.

TimeSlot shift slots

The parameter to this method is a time delta which is added both to the begin_at and the end_at fields of every Slot in the eadh_day list.

TimeSlot drop by pattern

The parameter to this method is a function (lambda) returning true if a given slot matches a pattern, false otherwise. The lambda parameter is passed to the JavaScript Array.filter method.

TimeSlotAgenda Methods

• constructor(day,index)
• set_start_and_end(st,et)
• add_slot(a_slot)
• find_slot(start_time)
• remove_slot(start_time)
• add_all_slots(slot_list)

TimeSlotAgenda Constructor

The day and index parameters correspond to day and index parametes required by the npm package, calendar-es6. In particular, the method getMap, constructs objects such as a TimeSlotAgenda. The constructor sets start time and end times to inifity values. A call to set_start_and_end will set the time to be the for the day specified by an application. Typically, this the times are midnight the previous day and at the end of the day.

TimeSlotAgenda set-start-and-end

The application sets the start and end times for the agenda, wich limits the slots that may be placed into it.

TimeSlotAgenda add slot

This method expects a Slot object which may be obtained from a TimeSlot. The Slot may only be added if it does not conflict with pre-existing TimeSlots in the TimeSlotAgenda list all_day.

If this conflicts are found, this method will return a list of conflicting Slots.

TimeSlotAgenda find slot

Given a time, this will look into the list, all_day and search for an event that either starts with the time or includes the time. (Note: a very small amount of extra time is needed to search for inclusive times.)

The method returns the slot if it is found false otherwise.

TimeSlotAgenda remove slot

This method takes a Slot as its parameter. The slot will be removed from its lists.

TimeSlotAgenda add_all slots

Given a list of Slots, this method will attempt to add all of them to the list, all_day. This method acrues the list of conflicts for each Slot in the parameter list and returns final list. It will add the Slots for which there is no conflict.

MonthContainer Methods

• constructor(start_time)
• get_day_agenda(indx)
• add_agenda_list(day_agenda)
• add_time_slot(a_t_slot)
• remove_time_slot(start_time)
• remove_all_of_time_slot(a_t_slot)

MonthContainer Constructor

The MonthContainer constructor takes a parameter that may either be a timestamp, such as the one returbed by Date.now(), or it may take a list (array) of parametes corresponding to the parameters for new Date(...parameters).

This constructor calls upon the methods of the npm package 'calendar-es6. It creates the month data structure needed for the MonthContainer's bookkeeping.

MonthContainer get day agenda

Given an index of a day into the MonthCatainer's cal.list of day keys, this method returns a TimeSlotAgenda for the given day.

MonthContainer add agenda list

Given a TimeSlotAgenda with Slots in its list, all_day, this method attempts to put all the Slots into the all_day list of the TimeSlotAgenda mapped to the same day as that of the parameter. All Slots are added unless there are conflicsts. A list of conflicts is returned.

MonthContainer add time slot

This method, given a TimeSlot, adds all the Slots of each day that match a day in the MonthContainer

MonthContainer remove time slot

This method removes all the slots from the MonthContainer that match the begin_at times of the Slots matching the timestamp passed in the parameter. This method removes the slots from the TimeSlotAgendas in the the map of days belonging to the MonthContainer. Usually just one Slot matches the timestamp.

MonthContainer remove all of time slot

This method removes all slots from a MonthContainer that match with Slot begin_at times belonging to the Slots stored in the TimeSlot each_day list.

Customization

There are a few classes that may be basic to an application's information storage requirements. These are the following:

• Slot
• TimeSlotAgenda

These classes offer basic fields and methods for their use within the context of MonthContainers and TimeLines.

By extending these classes, an application can store all the information needed to fit its requirements. The extending class can be passed as a last parameter to constructors. Passing the last parameter will provide the use of the extending class only if it actually extends the classes. The constructors default to the basic verion if the classes passed are not descendants of these classes.

For example, an application can extend a Slot:

import {EventDays} from 'event-days'

const Slot = EventDays.Slot

class SpecialSlot extends Slot {
	constructor(label,start_time,end_time) {
		super(label,start_time,end_time)
		
		this.special_field = "special value"
	}
}

Next, the SpecialSlot class can be used in the creation of a TimeSlot.

const TimeSlot = EventDays. TimeSlot

let a_t_slot = new TimeSlot("label", TimeSLot.USE_AS_OPEN,
                              start_time, end_time, false, 1.0, false,
                              daily_dur, false, SpecialSlot)