DateTime

Kind: Type

Source: atloria-monorepo/apps/parser-orchestrator/test/fixtures/sample-projects/fullstack-nextjs-nestjs/backend/api/schema.graphql

Custom scalar for date-time

DateTime is a custom GraphQL scalar used to represent date-time values in a consistent, API-friendly format. It’s typically serialized as an ISO-8601 string in responses and parsed/validated on input to ensure clients and services exchange timestamps reliably across the system.

Diagram

mermaid
graph LR
  Client[GraphQL Client] -->|Query/Mutation with DateTime| API[GraphQL API]
  API -->|Parse & validate| Scalar[DateTime Scalar]
  Scalar -->|Convert to JS Date / internal representation| Resolvers[Resolvers]
  Resolvers -->|Return DateTime| Scalar
  Scalar -->|Serialize ISO-8601 string| Client

Usage

ts
import { GraphQLScalarType, Kind } from "graphql";

// Example DateTime scalar implementation (ISO-8601)
export const DateTime = new GraphQLScalarType({
  name: "DateTime",
  description: "Custom scalar for date-time",
  serialize(value: unknown): string {
    const date = value instanceof Date ? value : new Date(String(value));
    if (Number.isNaN(date.getTime())) throw new TypeError("DateTime cannot serialize invalid date");
    return date.toISOString();
  },
  parseValue(value: unknown): Date {
    const date = new Date(String(value));
    if (Number.isNaN(date.getTime())) throw new TypeError("DateTime cannot parse invalid date");
    return date;
  },
  parseLiteral(ast): Date {
    if (ast.kind !== Kind.STRING) throw new TypeError("DateTime must be a string literal");
    const date = new Date(ast.value);
    if (Number.isNaN(date.getTime())) throw new TypeError("DateTime cannot parse invalid date");
    return date;
  },
});

// Example usage in schema (SDL):
// scalar DateTime
// type Event { id: ID!, startsAt: DateTime! }

// Example resolver returning a JS Date (will serialize to ISO string)
export const resolvers = {
  DateTime,
  Query: {
    serverTime: () => new Date(),
  },
  Mutation: {
    createEvent: (_: unknown, args: { startsAt: Date }) => ({
      id: "evt_123",
      startsAt: args.startsAt, // parsed by DateTime.parseValue
    }),
  },
};

AI Coding Instructions

• Treat DateTime values as ISO-8601 strings at the GraphQL boundary; convert to Date (or your internal time type) inside resolvers/services.
• Validate inputs aggressively (Invalid Date checks) to avoid silently accepting malformed timestamps and propagating bad data.
• Be explicit about timezone behavior: prefer toISOString() (UTC) for serialization to keep client/server consistent.
• When integrating with DB/ORM layers, standardize on one representation (e.g., store as UTC, return Date objects to GraphQL so the scalar can serialize).
• Avoid accepting non-string literals in parseLiteral unless you intentionally support them; mixed formats are a common source of client incompatibilities.

Referenced By

• User (TYPE_OF)
• User (TYPE_OF)
• Post (TYPE_OF)
• Post (TYPE_OF)
• Post (TYPE_OF)
• Comment (TYPE_OF)
• Comment (TYPE_OF)
• Like (TYPE_OF)
• Follow (TYPE_OF)