@paroicms/public-server-lib 0.45.2 → 0.46.0

package/dist/index.d.ts

@@ -3,9 +3,12 @@ export type * from "../typeonly/configuration-types.d.ts";
 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 * from "./api-error-handler.js";
 export * from "./html-helpers.js";
+export * from "./load-descriptors.js";
 export * from "./obfuscate.helper.js";
 export * from "./server-image-cache-engine.helper.js";
 export * from "./simple-i18n.js";
+export * from "./site-schema-public-helpers.js";
 export * from "./typeonly-validator.js";

package/dist/index.js

@@ -1,7 +1,9 @@
 export * from "./api-error-handler.js";
 export * from "./html-helpers.js";
+export * from "./load-descriptors.js";
 export * from "./obfuscate.helper.js";
 export * from "./server-image-cache-engine.helper.js";
 export * from "./simple-i18n.js";
+export * from "./site-schema-public-helpers.js";
 export * from "./typeonly-validator.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC"}
+{"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,uBAAuB,CAAC;AACtC,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC"}

package/dist/load-descriptors.d.ts

@@ -0,0 +1,19 @@
+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 WithOneDocumentLoadDescriptor {
+    [loadDescriptorSymbol]: OneDocumentLoadDescriptor;
+}
+export interface WithDocumentsLoadDescriptor {
+    [loadDescriptorSymbol]: DocumentsLoadDescriptor;
+}
+export declare function assignLoadDescriptor<T>(val: T, loadDescriptor: OneDocumentLoadDescriptor): T & WithOneDocumentLoadDescriptor;
+export declare function assignLoadDescriptor<T>(val: T, loadDescriptor: DocumentsLoadDescriptor): T & WithDocumentsLoadDescriptor;
+export declare function assignLoadDescriptor<T>(val: T, loadDescriptor: LoadDescriptor): T & WithLoadDescriptor;
+export declare function extractLoadDescriptor(val: unknown): LoadDescriptor | undefined;
+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/dist/load-descriptors.js

@@ -0,0 +1,42 @@
+const loadDescriptorSymbol = Symbol("loadDescriptor");
+export function assignLoadDescriptor(val, loadDescriptor) {
+    val[loadDescriptorSymbol] = loadDescriptor;
+    return val;
+}
+export function extractLoadDescriptor(val) {
+    if (typeof val !== "object" || val === null)
+        return;
+    if (!(loadDescriptorSymbol in val))
+        return;
+    const payload = val[loadDescriptorSymbol];
+    return payload;
+}
+export function extractOneDocumentLoadDescriptor(val) {
+    const payload = extractLoadDescriptor(val);
+    if (!payload)
+        return;
+    return payload.load === "one" && payload.nodeKind === "document" ? payload : undefined;
+}
+export function extractDocumentsLoadDescriptor(val) {
+    const payload = extractLoadDescriptor(val);
+    if (!payload)
+        return;
+    return payload.load === "list" && payload.nodeKind === "document" ? payload : undefined;
+}
+export function mergeListDescriptor(base, newValues) {
+    const target = { ...base };
+    if (newValues.labeledWith) {
+        target.labeledWith = newValues.labeledWith;
+    }
+    if (newValues.sorting) {
+        target.sorting = newValues.sorting;
+    }
+    if (newValues.offset !== undefined) {
+        target.offset = newValues.offset;
+    }
+    if (newValues.limit !== undefined) {
+        target.limit = newValues.limit;
+    }
+    return target;
+}
+//# sourceMappingURL=load-descriptors.js.map

package/dist/load-descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-descriptors.js","sourceRoot":"","sources":["../src/load-descriptors.ts"],"names":[],"mappings":"AAOA,MAAM,oBAAoB,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AA0BtD,MAAM,UAAU,oBAAoB,CAAC,GAAQ,EAAE,cAA8B;IAC3E,GAAG,CAAC,oBAAoB,CAAC,GAAG,cAAc,CAAC;IAC3C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO;IACpD,IAAI,CAAC,CAAC,oBAAoB,IAAI,GAAG,CAAC;QAAE,OAAO;IAC3C,MAAM,OAAO,GAAG,GAAG,CAAC,oBAAoB,CAAmB,CAAC;IAC5D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,GAAY;IAEZ,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,OAAO,OAAO,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,GAAY;IACzD,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,IAAO,EACP,SAA6B;IAE7B,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IAC3B,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QAC1B,MAAM,CAAC,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC;IAC7C,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IACrC,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;IACnC,CAAC;IACD,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/site-schema-public-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { ScSorting } from "@paroicms/public-anywhere-lib";
+import type { JtSorting } from "../typeonly/site-schema-json-types.js";
+export declare function parseSorting(val: JtSorting): ScSorting;

package/dist/site-schema-public-helpers.js

@@ -0,0 +1,15 @@
+export function parseSorting(val) {
+    if (val === "manual")
+        return "manual";
+    const regularChildrenSorting = [];
+    const arr = typeof val === "string" ? val.split(/\s*,\s*/) : val;
+    for (const item of arr) {
+        const [fieldName, direction] = item.split(/\s+/);
+        if ((direction !== "asc" && direction !== "desc") || !/^[a-zA-Z]+$/.test(fieldName)) {
+            throw new Error(`invalid child ordering '${item}'`);
+        }
+        regularChildrenSorting.push({ fieldName, direction });
+    }
+    return regularChildrenSorting;
+}
+//# sourceMappingURL=site-schema-public-helpers.js.map

package/dist/site-schema-public-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-schema-public-helpers.js","sourceRoot":"","sources":["../src/site-schema-public-helpers.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,YAAY,CAAC,GAAc;IACzC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAEtC,MAAM,sBAAsB,GAAiB,EAAE,CAAC;IAChD,MAAM,GAAG,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjE,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,KAAK,KAAK,IAAI,SAAS,KAAK,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,GAAG,CAAC,CAAC;QACtD,CAAC;QACD,sBAAsB,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,sBAAsB,CAAC;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paroicms/public-server-lib",
-  "version": "0.45.2",
+  "version": "0.46.0",
   "description": "Common utilitaries for paroicms plugins (backend side).",
   "author": "Paroi Team",
   "repository": {
@@ -15,16 +15,16 @@
   "scripts": {
     "build": "npm run typeonly && npm run tsc",
     "tsc": "tsc",
-    "typeonly": "typeonly --bundle dist/types.to.json -s ./typeonly",
+    "typeonly": "typeonly --bundle dist/types.to.json --source-dir typeonly",
     "test:watch": "vitest",
     "test": "vitest run",
     "clear": "rimraf dist/*",
     "dev": "tsc --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@paroicms/internal-anywhere-lib": "1.34.1",
-    "@paroicms/public-anywhere-lib": "0.35.1",
-    "@paroicms/script-lib": "0.2.2",
+    "@paroicms/internal-anywhere-lib": "1.35.0",
+    "@paroicms/public-anywhere-lib": "0.36.0",
+    "@paroicms/script-lib": "0.3.0",
     "@typeonly/validator": "~1.1.2",
     "arktype": "~2.1.20"
   },
@@ -32,7 +32,7 @@
     "@types/node": "~24.0.1",
     "rimraf": "~6.0.1",
     "typeonly": "~1.1.3",
-    "typescript": "~5.8.3",
+    "typescript": "~5.9.2",
     "vitest": "~3.2.3"
   },
   "files": [

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

@@ -17,6 +17,7 @@ import type {
   WithAttachedData,
 } from "@paroicms/public-anywhere-lib";
 import type Stream from "node:stream";
+import type { DocumentsLoadDescriptor } from "./load-descriptor-types.d.ts";
 
 export interface PaHttpContext {
   req: PaHttpRequest;
@@ -88,15 +89,11 @@ export interface BackendPluginInitService extends PluginStaticConfiguration {
     handler: PluginLiquidFilterHandler,
     options?: { raw?: boolean },
   ): void;
-  registerLiquidTag(
+  registerSetLiquidTagFunction(tagName: string, handler: PluginSetLiquidTagHandler): void;
+  registerOutLiquidTagFunction(
     tagName: string,
-    tagKind: "assignToVar",
-    handler: PluginLiquidTagReturnsVarHandler,
-  ): void;
-  registerLiquidTag(
-    tagName: string,
-    tagKind: "injectHtml",
-    handler: PluginLiquidTagReturnsHtmlHandler,
+    handler: PluginOutLiquidTagHandler,
+    options?: { raw?: boolean },
   ): void;
   registerHook(
     hookName: "initialized",
@@ -160,18 +157,21 @@ export type PluginLiquidFilterHandler = (
   },
 ) => string | undefined | Promise<string | undefined>;
 
-export type PluginLiquidTagReturnsVarHandler = (
+export type PluginSetLiquidTagHandler = (
   service: PluginRenderingService,
   options: {
-    mainParameter: unknown;
+    positionedParameters: unknown[];
     namedParameters: { [key: string]: unknown };
     variableName: string;
   },
-) => Generator;
+) => Generator<unknown, unknown, unknown>;
 
-export type PluginLiquidTagReturnsHtmlHandler = (
+export type PluginOutLiquidTagHandler = (
   service: PluginRenderingService,
-  parameters: { [key: string]: unknown },
+  options: {
+    positionedParameters: unknown[];
+    namedParameters: { [key: string]: unknown };
+  },
 ) => string | Promise<string>;
 
 export type PublicApiHandler = (
@@ -238,22 +238,20 @@ export interface PluginRenderingService {
   language: string;
   homeUrl: string;
   setRenderState(key: string, value: any): void;
-  renderChildPartials(
-    ctx: PaHttpContext,
-    options: {
-      params: PartialsParamsInput;
-      parentDocumentId: ParsedLNodeId;
-      labeledBy?: LabeledBy;
-    },
-  ): Promise<void>;
-  renderSearchPartials(
-    ctx: PaHttpContext,
-    options: {
-      language: string;
-      words: string[];
-      limit: number;
-      start: number;
-      templateName: string;
+
+  loadDocuments(loadDescriptor: DocumentsLoadDescriptor): Promise<TpDocument[]>;
+  loadDocuments(
+    loadDescriptor: DocumentsLoadDescriptor,
+    options: { withTotal: true },
+  ): Promise<{ documents: TpDocument[]; total: number }>;
+
+  renderDocument(templateName: string, doc: TpDocument): Promise<string>;
+
+  serve(
+    httpContext: PaHttpContext,
+    response: {
+      content: string;
+      contentType: string;
     },
   ): Promise<void>;
 
@@ -272,9 +270,10 @@ export interface PluginRenderingService {
   close(): Promise<void>;
 }
 
-export interface LabeledBy {
-  termNodeId: string;
-  fieldName: string;
+/** 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 interface PublicDocument {
@@ -324,12 +323,6 @@ export interface AppLogger {
   debug(...messages: any[]): void;
 }
 
-export interface PartialsParamsInput {
-  templateName: string;
-  offset: number;
-  limit: number;
-}
-
 export interface RegisteredSite {
   readonly fqdn: string;
   readonly siteName: string;

package/types/load-descriptor-types.d.ts

@@ -0,0 +1,43 @@
+import type { ParsedLNodeId, ScSorting } from "@paroicms/public-anywhere-lib";
+
+export type LoadDescriptor = DocumentsLoadDescriptor | OneDocumentLoadDescriptor;
+
+export type DocumentsLoadDescriptor = ChildDocumentsLoadDescriptor | SearchDocumentsLoadDescriptor;
+
+export interface ListBaseDescriptor {
+  offset?: number;
+  limit?: number;
+  sorting?: ScSorting;
+  labeledWith?: LabeledWithDescriptor;
+}
+
+export interface LabeledWithDescriptor {
+  fieldName: string;
+  termNodeId: string;
+}
+
+export interface ChildDocumentsLoadDescriptor extends ListBaseDescriptor {
+  load: "list";
+  nodeKind: "document";
+  descriptorName: "children";
+  parentDocumentId: ParsedLNodeId;
+  /**
+   * If omitted, an additional query to fetch the type name will be made to the database.
+   */
+  parentDocumentTypeName?: string;
+}
+
+export interface SearchDocumentsLoadDescriptor extends ListBaseDescriptor {
+  load: "list";
+  nodeKind: "document";
+  descriptorName: "search";
+  language: string;
+  words: string[];
+}
+
+export interface OneDocumentLoadDescriptor {
+  load: "one";
+  nodeKind: "document";
+  descriptorName: "id";
+  documentId: ParsedLNodeId;
+}