@paroicms/public-server-lib 0.50.2 → 0.50.4

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type * from "../typeonly/site-schema-json-types.d.ts";
 export type * from "../typeonly/theme-json-types.d.ts";
 export type * from "../types/backend-plugin-types.d.ts";
 export type * from "../types/load-descriptor-types.d.ts";
+export type * from "../types/template-payload.types.d.ts";
 export * from "./api-error-handler.js";
 export * from "./html-helpers.js";
 export * from "./load-descriptors.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC"}

package/dist/load-descriptors.d.ts

@@ -1,13 +1,12 @@
 import type { DocumentsLoadDescriptor, ListBaseDescriptor, LoadDescriptor, OneDocumentLoadDescriptor } from "../types/load-descriptor-types.js";
-declare const loadDescriptorSymbol: unique symbol;
-export interface WithLoadDescriptor<T extends LoadDescriptor = LoadDescriptor> {
-    [loadDescriptorSymbol]: T;
+export interface WithLoadDescriptor {
+    __notARealProperty__: "__load_descriptor__";
 }
 export interface WithOneDocumentLoadDescriptor {
-    [loadDescriptorSymbol]: OneDocumentLoadDescriptor;
+    __notARealProperty__: "__one_document_descriptor__";
 }
 export interface WithDocumentsLoadDescriptor {
-    [loadDescriptorSymbol]: DocumentsLoadDescriptor;
+    __notARealProperty__: "__documents_descriptor__";
 }
 export declare function assignLoadDescriptor<T>(val: T, loadDescriptor: OneDocumentLoadDescriptor): T & WithOneDocumentLoadDescriptor;
 export declare function assignLoadDescriptor<T>(val: T, loadDescriptor: DocumentsLoadDescriptor): T & WithDocumentsLoadDescriptor;
@@ -16,4 +15,3 @@ export declare function extractLoadDescriptor(val: unknown): LoadDescriptor | un
 export declare function extractOneDocumentLoadDescriptor(val: unknown): OneDocumentLoadDescriptor | undefined;
 export declare function extractDocumentsLoadDescriptor(val: unknown): DocumentsLoadDescriptor | undefined;
 export declare function mergeListDescriptor<T extends ListBaseDescriptor>(base: T, newValues: ListBaseDescriptor): T;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paroicms/public-server-lib",
-  "version": "0.50.2",
+  "version": "0.50.4",
   "description": "Common utilitaries for paroicms plugins (backend side).",
   "author": "Paroi Team",
   "repository": {
@@ -22,9 +22,9 @@
     "dev": "tsc --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@paroicms/internal-anywhere-lib": "1.37.1",
-    "@paroicms/public-anywhere-lib": "0.41.1",
-    "@paroicms/script-lib": "0.3.13",
+    "@paroicms/internal-anywhere-lib": "1.37.3",
+    "@paroicms/public-anywhere-lib": "0.41.3",
+    "@paroicms/script-lib": "0.3.15",
     "@typeonly/validator": "~1.1.2",
     "arktype": "~2.1.29"
   },
@@ -33,7 +33,7 @@
     "rimraf": "~6.1.2",
     "typeonly": "~1.1.3",
     "typescript": "~5.9.3",
-    "vitest": "~4.0.16"
+    "vitest": "~4.0.17"
   },
   "files": [
     "dist",

package/types/backend-plugin-types.d.ts

@@ -18,6 +18,7 @@ import type {
 } from "@paroicms/public-anywhere-lib";
 import type Stream from "node:stream";
 import type { DocumentsLoadDescriptor } from "./load-descriptor-types.d.ts";
+import type { TpDocPayload } from "./template-payload.types.d.ts";
 
 export interface PaHttpContext {
   req: PaHttpRequest;
@@ -167,6 +168,8 @@ export type PluginSetLiquidTagHandler = (
     positionedParameters: unknown[];
     namedParameters: { [key: string]: unknown };
     variableName: string;
+    /** The document currently being rendered. May be undefined for detached documents. */
+    document: PluginRenderedDocument | undefined;
   },
 ) => Generator<unknown, unknown, unknown>;
 
@@ -175,9 +178,26 @@ export type PluginOutLiquidTagHandler = (
   options: {
     positionedParameters: unknown[];
     namedParameters: { [key: string]: unknown };
+    /** The document currently being rendered. May be undefined for detached documents. */
+    document: PluginRenderedDocument | undefined;
   },
 ) => string | Promise<string>;
 
+export interface PublicDocumentBase {
+  id: string;
+  typeName: string;
+  nodeId: string;
+  language: string;
+  relativeId: string;
+  title?: string;
+  slug?: string;
+  publishDate: string;
+}
+
+export interface PluginRenderedDocument extends PublicDocumentBase {
+  url: string;
+}
+
 export type PublicApiHandler = (
   service: BackendPluginService,
   httpContext: PaHttpContext,
@@ -244,13 +264,13 @@ export interface PluginRenderingService {
   homeUrl: string;
   setRenderState(key: string, value: any): void;
 
-  loadDocuments(loadDescriptor: DocumentsLoadDescriptor): Promise<TpDocument[]>;
+  loadDocuments(loadDescriptor: DocumentsLoadDescriptor): Promise<LiquidPayload<TpDocPayload>[]>;
   loadDocuments(
     loadDescriptor: DocumentsLoadDescriptor,
     options: { withTotal: true },
-  ): Promise<{ documents: TpDocument[]; total: number }>;
+  ): Promise<{ documents: LiquidPayload<TpDocPayload>[]; total: number }>;
 
-  renderDocument(templateName: string, doc: TpDocument): Promise<string>;
+  renderDocument(templateName: string, doc: LiquidPayload<TpDocPayload>): Promise<string>;
 
   serve(
     httpContext: PaHttpContext,
@@ -275,22 +295,13 @@ export interface PluginRenderingService {
   close(): Promise<void>;
 }
 
-/** This type is a stub for `TpDocPayload`. It represents a full `doc` payload for LiquidJS templates. */
-export interface TpDocument {
-  kind: "routingDocument" | "regularDocument";
-  id: string;
-}
+export type LiquidPayload<T> = {
+  /** This is not true at runtime, it's a way to keep the typing. */
+  __nestedPayloadType__: T;
+};
 
-export interface PublicDocument {
-  id: string;
+export interface PublicDocument extends PublicDocumentBase {
   getUrl: (options?: { absoluteUrl?: boolean }) => Promise<string>;
-  typeName: string;
-  nodeId: string;
-  language: string;
-  relativeId: string;
-  title?: string;
-  slug?: string;
-  publishDate: string;
 }
 
 export interface PluginStaticConfigurations {

package/types/template-payload.types.d.ts

@@ -0,0 +1,285 @@
+export type TpTemplatePayload = TpDetachedTemplatePayload | TpRegularTemplatePayload;
+
+export interface TpDetachedTemplatePayload {
+  site: TpSitePayload;
+  doc: TpDetachedDocPayload;
+}
+
+export interface TpRegularTemplatePayload {
+  site: TpSitePayload;
+  doc: TpDocPayload;
+}
+
+export interface TpHomePayload {
+  baseUrl: string;
+  url: string;
+  id: string;
+  routing: TpRoutingClusterNode;
+  language: string;
+  languageLabel: string;
+}
+
+export interface TpSitePayload {
+  kind: "site";
+  fqdn: string;
+  /** @deprecated Use `home.baseUrl` instead */
+  url: string;
+  assetsUrl: string;
+  field: { [fieldName: string]: unknown };
+  home: TpHomePayload;
+  /** @deprecated Use `home.language` instead */
+  language: string;
+  /** @deprecated Use `home.languageLabel` instead */
+  languageLabel: string;
+
+  /** @deprecated */
+  fields: { [fieldName: string]: unknown };
+  /** @deprecated */
+  configuration: unknown;
+  /** @deprecated */
+  recaptchaKey?: string;
+}
+
+export interface TpClusterPayload {
+  kind: "cluster";
+  routing: TpRoutingClusterNode;
+  /** Lazy loaded */
+  parentCluster: TpClusterPayload | undefined;
+}
+
+export interface TpRoutingClusterNode extends TpOneDocumentLoadDescriptor {
+  id: string;
+  children: TpDocumentsLoadDescriptor | undefined;
+  /**
+   * TS forces us to declare all the types here but values will be only of type
+   * `TpRoutingClusterNode`.
+   */
+  [typeName: string]: TpRoutingClusterNode | TpDocumentsLoadDescriptor | string | undefined;
+}
+
+export interface TpDetachedDocPayload {
+  kind: "detached";
+  typeName?: string;
+  language?: string;
+  languageLabel?: string;
+  translations: TpDocTranslation[];
+  id?: string;
+  title?: string;
+  urlQuery: TpUrlQuery | undefined;
+  /** Lazy loaded */
+  cluster: TpClusterPayload;
+}
+
+export interface TpDocValues {
+  type: string;
+  nodeId: string;
+  language: string;
+  relativeId: string;
+  title?: string;
+  slug?: string;
+  /**
+   * ISO 8601 formatted date string. For preview document, it fallbacks to the current date
+   */
+  publishDate: string;
+  metaDescription?: string;
+  metaKeywords?: string;
+}
+
+export interface TpDocPayload extends TpDocValues {
+  kind: "routingDocument" | "regularDocument" | "term";
+  /** @deprecated */
+  leafType: string;
+  /** @deprecated */
+  leafId: string;
+  id: string;
+  languageLabel: string;
+  url: string;
+  excerpt?: string;
+  list: {
+    [listName: string]: TpPart[];
+  };
+  listSize: {
+    [listName: string]: number;
+  };
+  /** @deprecated */
+  defaultImageId?: string;
+  defaultImage?: TpImage;
+  /** @deprecated */
+  featuredImageId?: string;
+  featuredImage?: TpImage;
+  field: TpFieldValues;
+  /** @deprecated */
+  fields: TpFieldValues;
+  translations: TpDocTranslation[];
+  /** deprecated */
+  labeling: undefined;
+  /** deprecated */
+  singleLabeling: undefined;
+  /** deprecated */
+  flaggedWith: undefined;
+  /** deprecated */
+  flaggedWithOne: undefined;
+  og: TpOgValues;
+  breadcrumb: TpBreadcrumbItem[];
+  siblings: TpSiblingDocuments;
+  typeLabel: string;
+  urlQuery: TpUrlQuery | undefined;
+  frontendAppPath: string | undefined;
+  /**
+   * Child routing document identifiers. Available on routing document only.
+   */
+  routing?: TpRoutingClusterNode;
+  /** @deprecated Use `routing` instead */
+  routingIds?: TpRoutingClusterNode;
+  /** Lazy loaded */
+  cluster: TpClusterPayload;
+}
+
+export interface TpDocTranslation extends TpOneDocumentLoadDescriptor {
+  language: string;
+  languageLabel: string;
+  active: boolean;
+  url: string;
+}
+
+export interface TpTerm extends TpOneDocumentLoadDescriptor {
+  inRightLanguage: boolean;
+  language: string;
+  languageLabel: string;
+  nodeId: string;
+  /**
+   * The term title is the term document title.
+   */
+  title?: string;
+  url?: string;
+}
+
+export interface TpPartValues {
+  type: string;
+  relativeId: string;
+  number: number;
+  numberOfType: number;
+  inRightLanguage: boolean;
+  language: string;
+  languageLabel: string;
+  nodeId: string;
+  publishDate: string;
+}
+
+export interface TpPart extends TpPartValues {
+  kind: "part";
+  /** @deprecated */
+  leafId: string;
+  /** @deprecated */
+  leafType: string;
+  id: string;
+  /** @deprecated */
+  num: number;
+  /** @deprecated */
+  defaultImageId?: string;
+  defaultImage?: TpImage;
+  /** @deprecated */
+  featuredImageId?: string;
+  featuredImage?: TpImage;
+  field: TpFieldValues;
+  /** @deprecated */
+  fields: TpFieldValues;
+  typeLabel: string;
+  parts?: TpPart[];
+}
+
+export interface TpOgValues {
+  url: string;
+  type?: string;
+  image?: TpImageVariant;
+  title?: string;
+  siteName?: string;
+  description?: string;
+  locale?: string;
+}
+
+export interface TpBreadcrumbItem extends TpOneDocumentLoadDescriptor {
+  id: string;
+  title?: string;
+  url?: string;
+}
+
+export interface TpSiblingDocuments {
+  previous?: TpOneDocumentLoadDescriptor;
+  next?: TpOneDocumentLoadDescriptor;
+}
+
+export interface TpFieldValues {
+  [fieldName: string]: string | number | boolean | object | undefined;
+}
+
+export type TpMedia = TpFile | TpImage;
+export type TpSourceMedia = TpFile | TpSourceImage;
+export type TpImage = TpSourceImage | TpImageVariant;
+
+export interface TpMediaBase {
+  mediaId: string;
+  url: string;
+  mediaType: string;
+}
+
+export interface TpSourceBase {
+  isSource: true;
+  weightB: number;
+  originalName?: string;
+  attachedData?: TpAttachedData;
+}
+
+export interface TpAttachedData {
+  [propertyName: string]: string | number | boolean | object | undefined;
+  caption?: string;
+}
+
+export interface TpImageBase {
+  kind: "image";
+  rawWidth: number;
+  rawHeight: number;
+  /** Rendered width. Its value is equals to `round(rawWidth / pixelRatio)`. */
+  width: number;
+  /** Rendered height. Its value is equals to `round(rawHeight / pixelRatio)`. */
+  height: number;
+  pixelRatio: number;
+}
+
+export interface TpFile extends TpMediaBase, TpSourceBase {
+  kind: "file";
+}
+
+export interface TpSourceImage extends TpMediaBase, TpSourceBase, TpImageBase {}
+
+export interface TpImageVariant extends TpMediaBase, TpImageBase {
+  isSource: false;
+}
+
+export interface TpUrlQuery {
+  [key: string]: undefined | string | TpUrlQuery | (string | TpUrlQuery)[];
+}
+
+/**
+ * This type represents a load descriptor for multiple documents. The Liquid template can't access
+ * any property of this type. But it can use it to request loading of multiple documents, using the
+ * `docs` function, for example:
+ * ```
+ * {% set children = docs(doc.routing.children) %}
+ * ```
+ */
+export interface TpDocumentsLoadDescriptor {
+  __notARealProperty__: "__documents_descriptor__";
+}
+
+/**
+ * This type represents a load descriptor for a single document. The Liquid template can't access
+ * any property of this type. But it can use it to request loading of a single document, using the
+ * `doc` function, for example:
+ * ```
+ * {% set next = doc(doc.siblings.next) %}
+ * ```
+ */
+export interface TpOneDocumentLoadDescriptor {
+  __notARealProperty__: "__one_document_descriptor__";
+}