@jsondrop/drupal 0.0.0-stage → 0.1.1

package/src/entities.ts

@@ -0,0 +1,232 @@
+import type { ResourceBase, ToMany, ToOne } from '@jsondrop/core';
+import type { DateTimeString, FileMeta, FileUri, ImageMeta, LinkField, PathField, TextField } from './fields.js';
+
+/**
+ * Drupal 11 core entity types, with the base fields JSON:API exposes.
+ *
+ * Bundle-specific fields are the project's: extend the generic types and
+ * register the bundle.
+ *
+ * ```ts
+ * interface Article extends Node<'article'> {
+ *   body: TextField | null;
+ *   field_image: ToOne<File<ImageMeta>>;
+ *   field_tags: ToMany<Term<'tags'>>;
+ * }
+ * declare module '@jsondrop/core' {
+ *   interface ResourceTypes { 'node--article': Article }
+ * }
+ * ```
+ *
+ * Fields hidden by access (an anonymous request sees no `mail`) or by
+ * JSON:API Extras are absent at runtime even where typed as required.
+ */
+
+/** Fields shared by revisionable, translatable content entities. */
+interface ContentEntity<TType extends string> extends ResourceBase<TType> {
+  langcode: string;
+  default_langcode?: boolean;
+  revision_translation_affected?: boolean | null;
+}
+
+// Config entities: only the identifying fields are typed.
+
+export interface NodeType extends ResourceBase<'node_type--node_type'> {
+  drupal_internal__type: string;
+  name: string;
+  description: string | null;
+}
+
+export interface Vocabulary extends ResourceBase<'taxonomy_vocabulary--taxonomy_vocabulary'> {
+  drupal_internal__vid: string;
+  name: string;
+  description: string | null;
+}
+
+export interface MediaType extends ResourceBase<'media_type--media_type'> {
+  drupal_internal__id: string;
+  label: string;
+  description: string | null;
+}
+
+export interface Role extends ResourceBase<'user_role--user_role'> {
+  drupal_internal__id: string;
+  label: string;
+}
+
+export interface BlockContentType extends ResourceBase<'block_content_type--block_content_type'> {
+  drupal_internal__id: string;
+  label: string;
+}
+
+// Content entities.
+
+export interface User extends ContentEntity<'user--user'> {
+  drupal_internal__uid: number;
+  display_name: string;
+  name?: string;
+  mail?: string | null;
+  timezone?: string;
+  status?: boolean;
+  created?: DateTimeString;
+  changed?: DateTimeString;
+  access?: DateTimeString;
+  login?: DateTimeString | null;
+  preferred_langcode?: string;
+  roles?: ToMany<Role>;
+  user_picture?: ToOne<File<ImageMeta>>;
+}
+
+/**
+ * `file--file`. `TMeta` types the relationship meta it carries when reached
+ * through a field: {@link ImageMeta} for image fields.
+ */
+export interface File<TMeta extends object = Record<string, unknown>> extends ContentEntity<'file--file'> {
+  drupal_internal__fid: number;
+  filename: string;
+  uri: FileUri;
+  filemime: string;
+  filesize: number;
+  status: boolean;
+  created: DateTimeString;
+  changed: DateTimeString;
+  uid?: ToOne<User>;
+  relationshipMeta?: TMeta & Record<string, unknown>;
+}
+
+export interface Node<TBundle extends string = string> extends ContentEntity<`node--${TBundle}`> {
+  drupal_internal__nid: number;
+  drupal_internal__vid: number;
+  title: string;
+  status: boolean;
+  promote: boolean;
+  sticky: boolean;
+  created: DateTimeString;
+  changed: DateTimeString;
+  revision_timestamp?: DateTimeString;
+  revision_log?: string | null;
+  path?: PathField;
+  node_type?: ToOne<NodeType>;
+  uid?: ToOne<User>;
+  revision_uid?: ToOne<User>;
+}
+
+export interface Term<TVocabulary extends string = string> extends ContentEntity<`taxonomy_term--${TVocabulary}`> {
+  drupal_internal__tid: number;
+  drupal_internal__revision_id?: number;
+  name: string;
+  description: TextField | null;
+  weight: number;
+  status: boolean;
+  changed: DateTimeString;
+  path?: PathField;
+  vid?: ToOne<Vocabulary>;
+  /** Parents; a root term's parent is a stub with the id `virtual`. */
+  parent?: ToMany<Term<TVocabulary>>;
+  revision_user?: ToOne<User>;
+}
+
+export interface Media<TBundle extends string = string> extends ContentEntity<`media--${TBundle}`> {
+  drupal_internal__mid: number;
+  drupal_internal__vid: number;
+  name: string;
+  status: boolean;
+  created: DateTimeString;
+  changed: DateTimeString;
+  path?: PathField;
+  bundle?: ToOne<MediaType>;
+  thumbnail?: ToOne<File<ImageMeta>>;
+  uid?: ToOne<User>;
+  revision_user?: ToOne<User>;
+}
+
+// The media types the standard install profile creates.
+
+export interface MediaImage extends Media<'image'> {
+  field_media_image: ToOne<File<ImageMeta>>;
+}
+
+export interface MediaDocument extends Media<'document'> {
+  field_media_document: ToOne<File<FileMeta>>;
+}
+
+export interface MediaAudio extends Media<'audio'> {
+  field_media_audio_file: ToOne<File<FileMeta>>;
+}
+
+export interface MediaVideo extends Media<'video'> {
+  field_media_video_file: ToOne<File<FileMeta>>;
+}
+
+export interface MediaRemoteVideo extends Media<'remote_video'> {
+  /** The oEmbed URL (YouTube, Vimeo). */
+  field_media_oembed_video: string;
+}
+
+export interface MenuLinkContent extends ContentEntity<'menu_link_content--menu_link_content'> {
+  drupal_internal__id: number;
+  title: string;
+  description: string | null;
+  menu_name: string;
+  link: LinkField;
+  enabled: boolean;
+  expanded: boolean;
+  external: boolean;
+  weight: number;
+  /** Parent plugin ID, `menu_link_content:{uuid}`, or null at the root. */
+  parent: string | null;
+  changed: DateTimeString;
+}
+
+export interface BlockContent<TBundle extends string = string> extends ContentEntity<`block_content--${TBundle}`> {
+  drupal_internal__id: number;
+  info: string;
+  status: boolean;
+  reusable: boolean;
+  changed: DateTimeString;
+  body?: TextField | null;
+  block_content_type?: ToOne<BlockContentType>;
+}
+
+export interface PathAlias extends ResourceBase<'path_alias--path_alias'> {
+  drupal_internal__id: number;
+  langcode: string;
+  /** System path, e.g. `/node/1`. */
+  path: string;
+  alias: string;
+  status: boolean;
+}
+
+/** `paragraph--{bundle}` (contrib paragraphs). */
+export interface Paragraph<TBundle extends string = string> extends ContentEntity<`paragraph--${TBundle}`> {
+  drupal_internal__id: number;
+  drupal_internal__revision_id: number;
+  status: boolean;
+  created: DateTimeString;
+  parent_id: string;
+  parent_type: string;
+  parent_field_name: string;
+  behavior_settings?: unknown;
+}
+
+declare module '@jsondrop/core' {
+  interface ResourceTypes {
+    'user--user': User;
+    'file--file': File;
+    'menu_link_content--menu_link_content': MenuLinkContent;
+    'path_alias--path_alias': PathAlias;
+    'node_type--node_type': NodeType;
+    'taxonomy_vocabulary--taxonomy_vocabulary': Vocabulary;
+    'media_type--media_type': MediaType;
+    'user_role--user_role': Role;
+    'block_content_type--block_content_type': BlockContentType;
+  }
+
+  interface EntityTypes {
+    node: Node;
+    taxonomy_term: Term;
+    media: Media;
+    block_content: BlockContent;
+    paragraph: Paragraph;
+  }
+}

package/src/fields.ts

@@ -0,0 +1,81 @@
+/**
+ * Field value shapes, as Drupal 11's JSON:API normalizes core field types.
+ *
+ * Dates (`created`, `changed`, datetime fields) arrive as ISO 8601 strings.
+ */
+
+/** ISO 8601 date-time string, e.g. `2026-10-31T12:00:00+00:00`. */
+export type DateTimeString = string;
+
+/** `text_long`, `text_with_summary` (`summary` only on the latter). */
+export interface TextField {
+  value: string;
+  format: string | null;
+  /** The value rendered through its text format: safe HTML to output. */
+  processed: string;
+  summary?: string;
+}
+
+/** The `path` field (core path module). */
+export interface PathField {
+  alias: string | null;
+  pid: number | null;
+  langcode: string;
+}
+
+/** The `link` field type. */
+export interface LinkField {
+  /** `internal:/…`, `entity:node/1`, `route:<nolink>` or an external URL. */
+  uri: string;
+  title: string | null;
+  options: Record<string, unknown>;
+}
+
+/** The file field's `uri`: the stream URI and its (root-relative) URL. */
+export interface FileUri {
+  value: string;
+  url: string;
+}
+
+/**
+ * Relationship meta of an `image` field item, found on the file resource
+ * as `relationshipMeta`.
+ */
+export interface ImageMeta {
+  alt: string;
+  title: string;
+  width: number | null;
+  height: number | null;
+  drupal_internal__target_id: number;
+}
+
+/** Relationship meta of a `file` field item. */
+export interface FileMeta {
+  display: boolean | null;
+  description: string | null;
+  drupal_internal__target_id: number;
+}
+
+/** `datetime_range` / `daterange`. */
+export interface DateRangeField {
+  value: DateTimeString;
+  end_value: DateTimeString;
+}
+
+/** The `address` field (contrib address module, used by Commerce). */
+export interface AddressField {
+  country_code: string;
+  langcode?: string | null;
+  administrative_area?: string | null;
+  locality?: string | null;
+  dependent_locality?: string | null;
+  postal_code?: string | null;
+  sorting_code?: string | null;
+  address_line1?: string | null;
+  address_line2?: string | null;
+  address_line3?: string | null;
+  organization?: string | null;
+  given_name?: string | null;
+  additional_name?: string | null;
+  family_name?: string | null;
+}

package/src/files.ts

@@ -0,0 +1,52 @@
+import { isStub, type JsonApiClient } from '@jsondrop/core';
+import type { File } from './entities.js';
+import type { ImageMeta } from './fields.js';
+
+/**
+ * Absolute URL of a file. Drupal 11 serves `uri.url` root-relative
+ * (`/sites/default/files/…`); this prefixes the site's origin.
+ */
+export function fileUrl(client: JsonApiClient, file: Pick<File, 'uri'>): string {
+  const url = file.uri.url;
+  return /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//') ? url : `${client.baseUrl}${url}`;
+}
+
+/**
+ * URL of an image style derivative, as the consumer_image_styles module
+ * adds them to the file's links. NULL when the style is not enabled for
+ * the requesting consumer.
+ */
+export function imageStyleUrl(file: Pick<File, 'links'>, style: string): string | null {
+  return file.links?.[style]?.href ?? null;
+}
+
+export interface Image {
+  url: string;
+  alt: string;
+  title: string | null;
+  width: number | null;
+  height: number | null;
+}
+
+/**
+ * An image field's value, ready for an `<img>`: absolute URL plus the alt
+ * text and dimensions from the relationship. NULL for an empty field or a
+ * file that was not included.
+ */
+export function image(client: JsonApiClient, value: unknown): Image | null {
+  if (!value || typeof value !== 'object' || isStub(value)) {
+    return null;
+  }
+  const file = value as File<ImageMeta>;
+  if (!file.uri?.url) {
+    return null;
+  }
+  const meta: Partial<ImageMeta> = file.relationshipMeta ?? {};
+  return {
+    url: fileUrl(client, file),
+    alt: meta.alt ?? '',
+    title: meta.title || null,
+    width: meta.width ?? null,
+    height: meta.height ?? null,
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './account.js';
+export * from './entities.js';
+export * from './fields.js';
+export * from './files.js';
+export * from './menu.js';
+export * from './router.js';
+export * from './views.js';

package/src/menu.ts

@@ -0,0 +1,71 @@
+import type { JsonApiClient, ResourceBase, ResourceRequestOptions } from '@jsondrop/core';
+
+/**
+ * A menu link from the jsonapi_menu_items module. Unlike core's
+ * `menu_link_content` resources, it covers every link in the menu (links
+ * defined by modules too) and comes with a resolved `url`.
+ */
+export interface MenuItem extends ResourceBase {
+  /** Plugin ID: `menu_link_content:{uuid}`, `standard.front_page`, … */
+  id: string;
+  title: string;
+  description: string | null;
+  url: string;
+  menu_name: string;
+  /** Parent plugin ID, or empty at the root. */
+  parent: string;
+  weight: number;
+  enabled: boolean;
+  expanded: boolean;
+  provider: string;
+  route?: { name: string; parameters: Record<string, string> };
+  options?: Record<string, unknown>;
+}
+
+export type MenuTreeItem<T> = T & { children: MenuTreeItem<T>[] };
+
+/** A menu's enabled links, flat (jsonapi_menu_items module). */
+export async function getMenuItems(client: JsonApiClient, menu: string, options?: ResourceRequestOptions): Promise<MenuItem[]> {
+  const response = await client.get<MenuItem[]>(`/menu_items/${encodeURIComponent(menu)}`, options);
+  return response.data ?? [];
+}
+
+/** A menu as a tree, sorted by weight then title (jsonapi_menu_items module). */
+export async function getMenu(client: JsonApiClient, menu: string, options?: ResourceRequestOptions): Promise<MenuTreeItem<MenuItem>[]> {
+  return buildMenuTree(await getMenuItems(client, menu, options));
+}
+
+interface TreeInput {
+  id: string;
+  type?: string;
+  parent: string | null;
+  weight: number;
+  title: string;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Nests flat menu links by `parent`, sorted by weight then title. Takes
+ * jsonapi_menu_items links or core `menu_link_content` resources (whose
+ * `parent` names the plugin ID `menu_link_content:{uuid}`). A link whose
+ * parent is not in the list becomes a root.
+ */
+export function buildMenuTree<T extends TreeInput>(items: T[]): MenuTreeItem<T>[] {
+  const pluginId = (item: T) => (item.type === 'menu_link_content--menu_link_content' && UUID.test(item.id) ? `menu_link_content:${item.id}` : item.id);
+  const nodes = new Map<string, MenuTreeItem<T>>();
+  for (const item of items) {
+    nodes.set(pluginId(item), { ...item, children: [] });
+  }
+  const roots: MenuTreeItem<T>[] = [];
+  for (const node of nodes.values()) {
+    const parent = node.parent ? nodes.get(node.parent) : undefined;
+    (parent && parent !== node ? parent.children : roots).push(node);
+  }
+  const sort = (list: MenuTreeItem<T>[]) => {
+    list.sort((a, b) => a.weight - b.weight || a.title.localeCompare(b.title));
+    list.forEach((node) => sort(node.children));
+  };
+  sort(roots);
+  return roots;
+}

package/src/router.ts

@@ -0,0 +1,89 @@
+import { isJsonApiError, type JsonApiClient, type Resource, type ResourceRequestOptions } from '@jsondrop/core';
+
+/** What decoupled_router answers for a path. */
+export interface TranslatedPath {
+  /** Absolute URL the path resolves to. */
+  resolved: string;
+  isHomePath: boolean;
+  entity?: {
+    canonical: string;
+    type: string;
+    bundle: string;
+    /** Drupal's numeric ID, as a string. */
+    id: string;
+    uuid: string;
+  };
+  label?: string;
+  /** Present when the path is an entity JSON:API exposes. */
+  jsonapi?: {
+    individual: string;
+    resourceName: string;
+    pathPrefix: string;
+    basePath: string;
+    entryPoint: string;
+  };
+  /** Redirects (redirect module) that led here, oldest first. */
+  redirect?: Array<{ from: string; to: string; status: string }>;
+  [key: string]: unknown;
+}
+
+export interface ResolvedPath<T> {
+  route: TranslatedPath;
+  /** The entity at the path; NULL when the path is not a JSON:API entity. */
+  resource: T | null;
+}
+
+type PathOptions = Pick<ResourceRequestOptions, 'locale' | 'auth' | 'headers' | 'fetchOptions' | 'signal'>;
+
+/**
+ * Resolves a site path (`/about-us`, `/node/1`) with the decoupled_router
+ * module. NULL when nothing is there; a 403 (unpublished, no access) throws.
+ */
+export async function translatePath(client: JsonApiClient, path: string, options: PathOptions = {}): Promise<TranslatedPath | null> {
+  try {
+    const response = await client.get<TranslatedPath>(client.siteUrl('/router/translate-path', undefined, options.locale), {
+      ...options,
+      query: { params: { path, _format: 'json' } },
+      headers: { Accept: 'application/json', ...headersObject(options.headers) },
+      parse: 'json',
+    });
+    return response.data;
+  }
+  catch (error) {
+    if (isJsonApiError(error) && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Resolves a path and fetches the entity there, in two requests. The entity
+ * is fetched from the URL decoupled_router gives, which respects resource
+ * paths renamed with JSON:API Extras and the path's language.
+ *
+ * ```ts
+ * const page = await getResourceByPath<Node>(drupal, params.slug, { query: { include: ['uid'] } });
+ * if (!page) notFound();
+ * if (page.route.redirect?.length) redirect(page.route.redirect.at(-1)!.to);
+ * ```
+ */
+export async function getResourceByPath<T = Resource>(client: JsonApiClient, path: string, options: ResourceRequestOptions = {}): Promise<ResolvedPath<T> | null> {
+  const route = await translatePath(client, path, options);
+  if (!route) {
+    return null;
+  }
+  if (!route.jsonapi?.individual) {
+    return { route, resource: null };
+  }
+  const response = await client.get<T>(route.jsonapi.individual, options);
+  return { route, resource: response.data };
+}
+
+function headersObject(headers: HeadersInit | undefined): Record<string, string> {
+  const result: Record<string, string> = {};
+  new Headers(headers).forEach((value, name) => {
+    result[name] = value;
+  });
+  return result;
+}

package/src/views.ts

@@ -0,0 +1,50 @@
+import type { JsonApiClient, Links, Meta, Resource, ResourceRequestOptions } from '@jsondrop/core';
+
+export interface ViewOptions extends Omit<ResourceRequestOptions, 'query'> {
+  /** Exposed filters, by identifier. */
+  filters?: Record<string, string | string[]>;
+  /** Contextual filter values, in order. */
+  arguments?: string[];
+  /** Exposed sort. */
+  sort?: { by: string; order?: 'ASC' | 'DESC' };
+  /** Zero-based page of the view's pager. */
+  page?: number;
+  /** Other parameters (`include` works). */
+  params?: Record<string, string | string[]>;
+}
+
+export interface ViewResult<T> {
+  data: T[];
+  /** Total result count, when the view has a pager. */
+  count: number | null;
+  meta: Meta;
+  links: Links;
+}
+
+/**
+ * Results of a view display (jsonapi_views module): the display's
+ * filters, sorts and pager, as JSON:API resources.
+ */
+export async function getView<T = Resource>(client: JsonApiClient, view: string, display: string, options: ViewOptions = {}): Promise<ViewResult<T>> {
+  const { filters, arguments: args, sort, page, params, ...rest } = options;
+  const query: Record<string, string | string[]> = { ...params };
+  for (const [name, value] of Object.entries(filters ?? {})) {
+    if (Array.isArray(value)) query[`views-filter[${name}][]`] = value;
+    else query[`views-filter[${name}]`] = value;
+  }
+  if (args?.length) query['views-argument[]'] = args;
+  if (sort) {
+    query['views-sort[sort_by]'] = sort.by;
+    if (sort.order) query['views-sort[sort_order]'] = sort.order;
+  }
+  if (page !== undefined) query.page = String(page);
+
+  const response = await client.get<T[]>(`/views/${encodeURIComponent(view)}/${encodeURIComponent(display)}`, { ...rest, query: { params: query } });
+  const count = response.meta.count;
+  return {
+    data: response.data ?? [],
+    count: count === undefined || count === null ? null : Number(count),
+    meta: response.meta,
+    links: response.links,
+  };
+}