CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-neo4j-driver

The official Neo4j driver for JavaScript applications, enabling connection to and interaction with Neo4j graph databases.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

temporal-types.mddocs/

Temporal Data Types

Neo4j temporal data types including dates, times, and durations with timezone support and comprehensive type checking.

Capabilities

Date Type

Represents a date without time components.

interface Date {
  /** Year component */
  year: Integer;
  
  /** Month component (1-12) */
  month: Integer;
  
  /** Day component (1-31) */
  day: Integer;
  
  /** Convert to ISO date string (YYYY-MM-DD) */
  toString(): string;
}

/**
 * Check if an object is a Neo4j Date
 * @param obj - Object to check
 * @returns true if object is a Date instance
 */
function isDate(obj: any): obj is Date;

Usage Examples:

import { driver, auth, isDate } from "neo4j-driver";

const session = neo4jDriver.session();

try {
  const result = await session.run(`
    CREATE (e:Event {
      name: $name,
      startDate: date($dateStr),
      endDate: date() // Current date
    })
    RETURN e.startDate AS start, e.endDate AS end
  `, {
    name: "Conference 2024",
    dateStr: "2024-06-15"
  });
  
  const record = result.records[0];
  const startDate = record.get("start");
  const endDate = record.get("end");
  
  if (isDate(startDate)) {
    console.log(`Event starts on: ${startDate.toString()}`); // "2024-06-15"
    console.log(`Year: ${startDate.year}, Month: ${startDate.month}, Day: ${startDate.day}`);
  }
  
  if (isDate(endDate)) {
    console.log(`Event ends on: ${endDate.toString()}`);
  }
} finally {
  await session.close();
}

DateTime Type

Represents a date and time with optional timezone information.

interface DateTime {
  /** Year component */
  year: Integer;
  
  /** Month component (1-12) */
  month: Integer;
  
  /** Day component (1-31) */
  day: Integer;
  
  /** Hour component (0-23) */
  hour: Integer;
  
  /** Minute component (0-59) */
  minute: Integer;
  
  /** Second component (0-59) */
  second: Integer;
  
  /** Nanosecond component (0-999999999) */
  nanosecond: Integer;
  
  /** Timezone offset in seconds (optional) */
  timeZoneOffsetSeconds?: Integer;
  
  /** Timezone identifier (optional) */
  timeZoneId?: string;
  
  /** Convert to ISO datetime string */
  toString(): string;
}

/**
 * Check if an object is a Neo4j DateTime
 * @param obj - Object to check
 * @returns true if object is a DateTime instance
 */
function isDateTime(obj: any): obj is DateTime;

Usage Examples:

const result = await session.run(`
  CREATE (log:LogEntry {
    message: $message,
    timestamp: datetime(),
    scheduledFor: datetime($futureTime)
  })
  RETURN log.timestamp AS now, log.scheduledFor AS future
`, {
  message: "System started",
  futureTime: "2024-12-25T09:00:00Z"
});

const record = result.records[0];
const now = record.get("now");
const future = record.get("future");

if (isDateTime(now)) {
  console.log(`Current time: ${now.toString()}`);
  console.log(`${now.year}-${now.month}-${now.day} ${now.hour}:${now.minute}:${now.second}`);
  
  if (now.timeZoneId) {
    console.log(`Timezone: ${now.timeZoneId}`);
  } else if (now.timeZoneOffsetSeconds !== undefined) {
    console.log(`Timezone offset: ${now.timeZoneOffsetSeconds} seconds`);
  }
}

if (isDateTime(future)) {
  console.log(`Scheduled for: ${future.toString()}`);
  console.log(`Christmas morning: ${future.month}/25 at ${future.hour}:00`);
}

LocalDateTime Type

Represents a date and time without timezone information.

interface LocalDateTime {
  /** Year component */
  year: Integer;
  
  /** Month component (1-12) */
  month: Integer;
  
  /** Day component (1-31) */
  day: Integer;
  
  /** Hour component (0-23) */
  hour: Integer;
  
  /** Minute component (0-59) */
  minute: Integer;
  
  /** Second component (0-59) */
  second: Integer;
  
  /** Nanosecond component (0-999999999) */
  nanosecond: Integer;
  
  /** Convert to ISO local datetime string */
  toString(): string;
}

/**
 * Check if an object is a Neo4j LocalDateTime
 * @param obj - Object to check
 * @returns true if object is a LocalDateTime instance
 */
function isLocalDateTime(obj: any): obj is LocalDateTime;

Usage Examples:

const result = await session.run(`
  CREATE (appt:Appointment {
    title: $title,
    localTime: localdatetime($timeStr),
    created: localdatetime()
  })
  RETURN appt.localTime AS scheduled, appt.created AS created
`, {
  title: "Team Meeting",
  timeStr: "2024-06-15T14:30:00"
});

const record = result.records[0];
const scheduled = record.get("scheduled");
const created = record.get("created");

if (isLocalDateTime(scheduled)) {
  console.log(`Meeting scheduled: ${scheduled.toString()}`); // "2024-06-15T14:30:00"
  console.log(`Date: ${scheduled.year}-${scheduled.month}-${scheduled.day}`);
  console.log(`Time: ${scheduled.hour}:${scheduled.minute}`);
}

if (isLocalDateTime(created)) {
  console.log(`Appointment created: ${created.toString()}`);
}

Time Type

Represents a time with timezone information.

interface Time {
  /** Hour component (0-23) */
  hour: Integer;
  
  /** Minute component (0-59) */
  minute: Integer;
  
  /** Second component (0-59) */
  second: Integer;
  
  /** Nanosecond component (0-999999999) */
  nanosecond: Integer;
  
  /** Timezone offset in seconds (optional) */
  timeZoneOffsetSeconds?: Integer;
  
  /** Timezone identifier (optional) */
  timeZoneId?: string;
  
  /** Convert to ISO time string */
  toString(): string;
}

/**
 * Check if an object is a Neo4j Time
 * @param obj - Object to check
 * @returns true if object is a Time instance
 */
function isTime(obj: any): obj is Time;

Usage Examples:

const result = await session.run(`
  CREATE (schedule:DailySchedule {
    name: $name,
    startTime: time($startStr),
    endTime: time($endStr),
    currentTime: time()
  })
  RETURN schedule.startTime AS start, schedule.endTime AS end, schedule.currentTime AS current
`, {
  name: "Work Hours",
  startStr: "09:00:00+02:00",
  endStr: "17:30:00+02:00"
});

const record = result.records[0];
const startTime = record.get("start");
const endTime = record.get("end");
const currentTime = record.get("current");

if (isTime(startTime)) {
  console.log(`Work starts at: ${startTime.toString()}`); // "09:00:00+02:00"
  console.log(`Hour: ${startTime.hour}, Minute: ${startTime.minute}`);
  
  if (startTime.timeZoneId) {
    console.log(`Timezone: ${startTime.timeZoneId}`);
  } else if (startTime.timeZoneOffsetSeconds !== undefined) {
    console.log(`Offset: ${startTime.timeZoneOffsetSeconds / 3600} hours`);
  }
}

if (isTime(endTime)) {
  console.log(`Work ends at: ${endTime.toString()}`);
}

LocalTime Type

Represents a time without timezone information.

interface LocalTime {
  /** Hour component (0-23) */
  hour: Integer;
  
  /** Minute component (0-59) */
  minute: Integer;
  
  /** Second component (0-59) */
  second: Integer;
  
  /** Nanosecond component (0-999999999) */
  nanosecond: Integer;
  
  /** Convert to ISO local time string */
  toString(): string;
}

/**
 * Check if an object is a Neo4j LocalTime
 * @param obj - Object to check
 * @returns true if object is a LocalTime instance
 */
function isLocalTime(obj: any): obj is LocalTime;

Usage Examples:

const result = await session.run(`
  CREATE (routine:DailyRoutine {
    activity: $activity,
    localStartTime: localtime($timeStr),
    currentLocalTime: localtime()
  })
  RETURN routine.localStartTime AS start, routine.currentLocalTime AS current
`, {
  activity: "Morning Workout",
  timeStr: "06:30:00"
});

const record = result.records[0];
const startTime = record.get("start");

if (isLocalTime(startTime)) {
  console.log(`Workout starts at: ${startTime.toString()}`); // "06:30:00"
  console.log(`${startTime.hour}:${startTime.minute} (local time)`);
}

Duration Type

Represents a temporal duration between two points in time.

interface Duration {
  /** Number of months in the duration */
  months: Integer;
  
  /** Number of days in the duration */
  days: Integer;
  
  /** Number of seconds in the duration */
  seconds: Integer;
  
  /** Number of nanoseconds in the duration */
  nanoseconds: Integer;
  
  /** Convert to ISO duration string */
  toString(): string;
}

/**
 * Check if an object is a Neo4j Duration
 * @param obj - Object to check
 * @returns true if object is a Duration instance
 */
function isDuration(obj: any): obj is Duration;

Usage Examples:

const result = await session.run(`
  MATCH (start:Event {name: $startEvent}), (end:Event {name: $endEvent})
  WITH start, end, duration.between(start.timestamp, end.timestamp) AS eventDuration
  CREATE (span:TimeSpan {
    startEvent: start.name,
    endEvent: end.name,
    duration: eventDuration,
    calculatedAt: datetime()
  })
  RETURN span.duration AS duration
`, {
  startEvent: "Project Start",
  endEvent: "Project End"
});

const record = result.records[0];
const duration = record.get("duration");

if (isDuration(duration)) {
  console.log(`Project duration: ${duration.toString()}`); // "P2M15DT8H30M"
  
  // Break down duration components
  console.log(`Months: ${duration.months}`);
  console.log(`Days: ${duration.days}`);
  console.log(`Hours: ${Math.floor(duration.seconds.toNumber() / 3600)}`);
  console.log(`Minutes: ${Math.floor((duration.seconds.toNumber() % 3600) / 60)}`);
  console.log(`Seconds: ${duration.seconds.toNumber() % 60}`);
  
  // Convert to approximate total days
  const totalDays = duration.months.toNumber() * 30 + duration.days.toNumber() + 
                   duration.seconds.toNumber() / (24 * 3600);
  console.log(`Approximately ${totalDays.toFixed(1)} total days`);
}

// Create durations in Cypher
const createResult = await session.run(`
  CREATE (task:Task {
    name: $name,
    estimatedDuration: duration($durationStr),
    warningThreshold: duration({hours: 2}),
    maxDuration: duration({days: 7, hours: 12, minutes: 30})
  })
  RETURN task.estimatedDuration AS estimated,
         task.warningThreshold AS warning,
         task.maxDuration AS max
`, {
  name: "Data Migration",
  durationStr: "PT4H30M" // 4 hours 30 minutes
});

createResult.records.forEach(record => {
  const estimated = record.get("estimated");
  const warning = record.get("warning");
  const max = record.get("max");
  
  if (isDuration(estimated)) {
    console.log(`Estimated time: ${estimated.toString()}`);
  }
  if (isDuration(warning)) {
    console.log(`Warning threshold: ${warning.toString()}`);
  }
  if (isDuration(max)) {
    console.log(`Maximum duration: ${max.toString()}`);
  }
});

Temporal Type Utilities

Utility object containing all temporal type checking functions.

declare const temporal: {
  /** Check if object is a Date */
  isDate: typeof isDate;
  
  /** Check if object is a DateTime */
  isDateTime: typeof isDateTime;
  
  /** Check if object is a LocalDateTime */
  isLocalDateTime: typeof isLocalDateTime;
  
  /** Check if object is a Time */
  isTime: typeof isTime;
  
  /** Check if object is a LocalTime */
  isLocalTime: typeof isLocalTime;
  
  /** Check if object is a Duration */
  isDuration: typeof isDuration;
};

Usage Examples:

import { temporal } from "neo4j-driver";

const result = await session.run(`
  RETURN date() AS currentDate,
         datetime() AS currentDateTime,
         time() AS currentTime,
         localdatetime() AS localNow,
         localtime() AS localTime,
         duration({hours: 2, minutes: 30}) AS sampleDuration
`);

const record = result.records[0];

// Generic temporal type analysis
function analyzeTemporalValue(value: any, name: string) {
  if (temporal.isDate(value)) {
    console.log(`${name} is a Date: ${value.toString()}`);
  } else if (temporal.isDateTime(value)) {
    console.log(`${name} is a DateTime: ${value.toString()}`);
    if (value.timeZoneId) {
      console.log(`  Timezone: ${value.timeZoneId}`);
    }
  } else if (temporal.isLocalDateTime(value)) {
    console.log(`${name} is a LocalDateTime: ${value.toString()}`);
  } else if (temporal.isTime(value)) {
    console.log(`${name} is a Time: ${value.toString()}`);
  } else if (temporal.isLocalTime(value)) {
    console.log(`${name} is a LocalTime: ${value.toString()}`);
  } else if (temporal.isDuration(value)) {
    console.log(`${name} is a Duration: ${value.toString()}`);
  } else {
    console.log(`${name} is not a temporal type`);
  }
}

// Analyze all temporal values
record.keys.forEach(key => {
  analyzeTemporalValue(record.get(key), key);
});

// Working with temporal comparisons
const comparisonResult = await session.run(`
  WITH datetime('2024-06-15T10:30:00Z') AS start,
       datetime('2024-06-15T14:45:00Z') AS end
  RETURN start < end AS isBefore,
         duration.between(start, end) AS timeDiff,
         start + duration({hours: 3}) AS startPlusThree
`);

const compRecord = comparisonResult.records[0];
console.log(`Start is before end: ${compRecord.get("isBefore")}`);

const timeDiff = compRecord.get("timeDiff");
if (temporal.isDuration(timeDiff)) {
  console.log(`Time difference: ${timeDiff.toString()}`);
}

const startPlusThree = compRecord.get("startPlusThree");
if (temporal.isDateTime(startPlusThree)) {
  console.log(`Start + 3 hours: ${startPlusThree.toString()}`);
}

docs

authentication.md

driver-management.md

error-handling.md

graph-types.md

index.md

reactive-programming.md

session-operations.md

temporal-types.md

transaction-management.md

tile.json