nextpress-core 1.0.0

package/lib/acf-functions/types/acf-layout.d.ts

@@ -0,0 +1,20 @@
+type TransformACFLayout<T> = T extends any
+    ? Omit<T, 'key' | 'sub_fields'> &
+        ('sub_fields' extends keyof T ? { sub_fields: NextpressField[] } : [])
+    : never;
+
+/** ACF Layout without key constraints to allow key generation */
+type NextpressLayout = TransformACFLayout<ACFLayout>
+
+/**
+ * Represents a layout within an ACF Flexible Content field.
+ */
+type ACFLayout = {
+    key: string,
+    name: string,
+    label: string,
+    display: 'table' | 'block' | 'row',
+    sub_fields: ACFField[],
+    min?: string,
+    max?: string
+}

package/lib/acf-functions/types/acf-values.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Represents raw ACF values retrieved from the database.
+ */
+type ACFRawValues = Map<string, string>;

package/lib/acf-functions/types/components/field-props.d.ts

@@ -0,0 +1,189 @@
+import { IPost } from "@/lib/nextpress/entities/post/post.interface";
+import { ITerm } from "@/lib/nextpress/entities/term/term.interface";
+import { IUser } from "@/lib/nextpress/entities/user/user.interface";
+import { JSX } from "react";
+
+type GetFields<T> =
+    T extends { fields: readonly any[] } ? T['fields']
+    : T extends { sub_fields: readonly any[] } ? T['sub_fields']
+    : never;
+
+/**
+ * Represents the properties passed to a Nextpress ACF component.
+ *
+ * @template T - The expected type of the mapped ACF fields.
+ */
+type FieldProps<LayoutT> =
+    LayoutT extends { fields: readonly any[] } | { sub_fields: readonly any[] }
+        ? ResolvedFields<GetFields<LayoutT>>
+    : never;
+
+/**
+ * An array of ACF field configurations to a strongly-typed object representing the resolved data structure.
+ * It iterates over the array, using the `name` property of each field as the object key, and determines the expected value type using the `MapFieldType` utility.
+ *
+ * @template Fields - A readonly array of ACF field configuration objects.
+ */
+type ResolvedFields<Fields extends readonly any[]> = {
+    [F in Fields[number] as F['name']]: MapFieldType<F>
+};
+
+/**
+ * Maps an array of ACF Flexible Content layouts to a union type representing the resolved layout blocks.
+ * For each layout, it checks for the presence of `fields` or `sub_fields`, and resolves to a specific object
+ * structure containing the layout's React component and its deeply resolved field content.
+ *
+ * @template Layouts - A readonly array of ACF Flexible Content layout configuration objects.
+ */
+type ResolvedFlexibleContent<Layouts extends readonly any[]> = {
+    [L in Layouts[number] as L['name']]: L extends { name: infer Name } & ({ fields: readonly any[] } | { sub_fields: readonly any[] })
+        ? {
+            Component: () => Promise<JSX.Element>,
+            content: ResolvedFields<GetFields<L>>
+        }[]
+    : never
+}[Layouts[number]['name']];
+
+
+type MapFieldType<Field> =
+    Field extends { type: 'color_picker' }
+        ? string | null
+    : Field extends { type: 'date_picker' }
+        ? string | null
+    : Field extends { type: 'date_time_picker' }
+        ? string | null
+    : Field extends { type: 'google_map' }
+        ? ACFGoogleMapsObject | null
+    : Field extends { type: 'icon_picker' }
+        ? Field extends { return_format: 'string' }
+            ? string | null
+        : Field extends { return_format: 'array' }
+            ? ACFIconObject | null
+        : ACFIconObject | null
+    : Field extends { type: 'time_picker' }
+        ? string | null
+    : Field extends { type: 'email' }
+        ? string | null
+    : Field extends { type: 'number' }
+        ? number | null
+    : Field extends { type: 'password' }
+        ? string | null
+    : Field extends { type: 'range' }
+        ? number | null
+    : Field extends { type: 'text' }
+        ? string | null
+    : Field extends { type: 'textarea' }
+        ? string | null
+    : Field extends { type: 'button_group' }
+        ? Field extends { return_format: 'array' }
+            ? ACFChoiceObject | null
+        : string | null
+    : Field extends { type: 'checkbox' }
+        ? Field extends { return_format: 'array' }
+            ? ACFChoiceObject[]
+        : string[]
+    : Field extends { type: 'radio' }
+        ? Field extends { return_format: 'array' }
+            ? ACFChoiceObject | null
+        : string | null
+    : Field extends { type: 'select' }
+        ? Field extends { multiple: 1 }
+            ? Field extends { return_format: 'array' }
+                ? ACFChoiceObject[]
+            : string[]
+        : Field extends { return_format: 'array' }
+            ? ACFChoiceObject | null
+        : string | null
+    : Field extends { type: 'true_false' }
+        ? boolean
+    : Field extends { type: 'file' }
+        ? number | null
+    : Field extends { type: 'gallery' }
+        ? number[]
+    : Field extends { type: 'image' }
+        ? number | null
+    : Field extends { type: 'oembed' }
+        ? string | null
+    : Field extends { type: 'wysiwyg' }
+        ? string | null
+    : Field extends { type: 'link' }
+        ? Field extends { return_format: 'url' }
+            ? string | null
+        : Field extends { return_format: 'array' }
+            ? ACFLinkObject | null
+        : ACFLinkObject
+    : Field extends { type: 'page_link' }
+        ? Field extends { multiple: 1 }
+            ? string[]
+        : string | null
+    : Field extends { type: 'post_object' }
+        ? Field extends { multiple: 1 }
+            ? Field extends { return_format: 'object' }
+                ? IPost[]
+            : number[]
+        : Field extends { return_format: 'object' }
+            ? IPost | null
+        : number | null
+    : Field extends { type: 'relationship' }
+        ? Field extends { return_format: 'object' }
+            ? IPost[] | null
+        : number[] | null
+    : Field extends { type: 'taxonomy' }
+        ? Field extends { multiple: 1 }
+            ? Field extends { return_format: 'object' }
+                ? ITerm[]
+            : number[]
+        : Field extends { return_format: 'object' }
+            ? ITerm | null
+        : number | null
+    : Field extends { type: 'user' }
+        ? Field extends { multiple: 1 }
+            ? Field extends { return_format: 'object' }
+                ? IUser[]
+            : number[]
+        : Field extends { return_format: 'object' }
+            ? IUser | null
+        : number | null
+    : Field extends { type: 'group' } & ({ fields: readonly any[] } | { sub_fields: readonly any[] })
+        ? ResolvedFields<GetFields<Field>> | null
+    : Field extends { type: 'repeater' } & ({ fields: readonly any[] } | { sub_fields: readonly any[] })
+        ? ResolvedFields<GetFields<Field>>[] | null
+    : Field extends { type: 'flexible_content'; layouts: readonly any[] }
+        ? ResolvedFlexibleContent<Field['layouts']> | null
+    : Field extends { fields: readonly any[] } | { sub_fields: readonly any[] }
+        ? ResolvedFields<GetFields<Field>>
+    : never;
+
+type ACFIconObject = {
+    type: string,
+    value: string
+}
+
+type ACFLinkObject = {
+    title: string,
+    url: string,
+    target: string
+}
+
+type ACFChoiceObject = {
+    label?: string
+    value?: string,
+}
+
+type ACFGoogleMapsObject = {
+    address: string;
+    lat: string | number;
+    lng: string | number;
+    zoom: string | number;
+    place_id: string;
+    name: string;
+    street_number: string | number;
+    street_name: string;
+    street_name_short: string;
+    city: string;
+    state: string;
+    state_short: string;
+    post_code: string | number;
+    country: string;
+    country_short: string;
+}

package/lib/acf-functions/types/components/nextpress-component.d.ts

@@ -0,0 +1,11 @@
+import { JSX } from 'react';
+
+/**
+ * Represents a Next.js React component that consumes Nextpress ACF fields.
+ *
+ * @template T - The expected type of the mapped ACF fields.
+ */
+type NextpressComponent = {
+    layout: NextpressLayout
+    Component: () => Promise<JSX.Element>
+}

package/lib/ambient.d.ts

@@ -0,0 +1,15 @@
+declare module '*nextpress.config' {
+    const nextpressConfig: NextpressConfig;
+    export default nextpressConfig;
+}
+
+declare module '@/fonts' {
+    type NextFont = import('next/dist/compiled/@next/font').NextFont;
+
+    const fonts: NextFont[];
+    export default fonts;
+}
+
+declare module '@/app/_templates/layout' {
+    export const LayoutTemplate: ({ children }: Readonly<{children: import('react').React.ReactNode}>) => Promise<import('react').JSX.Element>;
+}

package/lib/entities/common.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Represents entity with a path.
+ */
+export interface IPath {
+    /** Nextpress path to entity. */
+    path: string
+}
+
+/**
+ * Array of field key-value pairs.
+ */
+type Fields = {
+    /** Field key. */
+    key: string,
+    /** Field value. */
+    value: string
+}[];
+
+/**
+ * Represents entity that can provide ACF fields.
+ */
+export interface IFieldLocation {
+    /**
+     * Retrieves fields matching a name prefix.
+     *
+     * @param {string} name - Field name prefix to search for.
+     * @returns {Promise<Fields>} Promise resolving to array of fields.
+     */
+    getFields: (name: string) => Promise<Fields>
+}

package/lib/entities/option/option.interface.d.ts

@@ -0,0 +1,8 @@
+import { Selectable } from "kysely";
+import { WpOption } from "../../wpdb/wpdb.interface";
+import { IFieldLocation } from "../common";
+
+/**
+ * Represents option entity.
+ */
+interface IOption extends Omit<Selectable<WpOption>, 'autoload'> {};

package/lib/entities/option/option.ts

@@ -0,0 +1,43 @@
+import { wpdb } from "@/wpdb/wpdb";
+import { IOption } from "./option.interface";
+
+/**
+ * Implementation of IOption entity.
+ */
+export class Option implements IOption
+{
+    constructor(public optionId: number) {};
+
+    /** Raw option data from database. */
+    private optionData?: Record<string, any>;
+
+    /**
+     * Retrieves array of Option instances by IDs.
+     *
+     * @param {number[]} ids - Array of option IDs to retrieve.
+     * @returns {Promise<Option[]>} Promise resolving to array of Option instances.
+     */
+    static async get(ids: number[]): Promise<Option[]> {
+        ids = ids.filter(Boolean);
+        if (!ids || !ids.length) return [];
+
+        const optionData = await wpdb
+            .selectFrom('wpOptions')
+            .where('optionId', 'in', ids)
+            .select(['optionId', 'optionName', 'optionValue'])
+            .execute();
+
+        const optionDataMap = new Map(optionData.map(option => [Number(option.optionId), option]));
+
+        return ids.map(id => {
+            const instance = new Option(id);
+
+            instance.optionData = optionDataMap.get(id);
+
+            return instance;
+        })
+    }
+
+    get optionName(): string { return this.optionData?.['optionName'] ?? ''};
+    get optionValue(): string { return this.optionData?.['optionValue'] ?? ''};
+}

package/lib/entities/post/post.interface.d.ts

@@ -0,0 +1,72 @@
+import { Selectable } from "kysely";
+import { WpPost } from "../../wpdb/wpdb.interface";
+import { IFieldLocation, IPath } from "../common";
+
+/**
+ * Attributes for post attachment images.
+ */
+type PostImageAttributes = {
+    /** Image source URL. */
+    src?: string,
+    /** Image alternative text. */
+    alt?: string,
+    /** Image height. */
+    height?: number,
+    /** Image width. */
+    width?: number,
+}
+
+/**
+ * Attributes for nav menu items.
+ */
+type MenuItemAttributes = {
+    /** Menu item label. */
+    label: string,
+    /** Menu item type. */
+    type: 'custom' | 'post_type' | 'taxonomy',
+    /** Parent menu item ID. */
+    parentId: number,
+    /** Target object ID. */
+    objectId: number,
+    /** Menu item URL. */
+    url: string,
+}
+
+/**
+ * Base post properties.
+ */
+interface IBasePost extends Selectable<WpPost> {}
+
+/**
+ * Page post properties.
+ */
+interface IPagePost extends IBasePost, IPath {}
+
+/**
+ * Standard post properties.
+ */
+interface IPostPost extends IBasePost, IPath {
+    /** Featured image attachment ID. */
+    thumbnailId: number,
+}
+
+/**
+ * Attachment post properties.
+ */
+interface IAttachmentPost extends IBasePost {
+    /** Image attributes. */
+    imageAttributes: PostImageAttributes,
+}
+
+/**
+ * Menu item properties.
+ */
+interface IMenuItem extends IBasePost {
+    /** Menu item attributes. */
+    menuItemAttributes: MenuItemAttributes | null
+}
+
+/**
+ * Comprehensive post entity encompassing all post types.
+ */
+interface IPost extends IBasePost, IPagePost, IPostPost, IAttachmentPost, IMenuItem, IFieldLocation {};

package/lib/entities/post/post.ts

@@ -0,0 +1,209 @@
+import { unserialize } from "php-serialize";
+import { Fields } from "../common";
+import { IPost, PostImageAttributes, MenuItemAttributes } from "./post.interface";
+import { processURL } from "@/services/utilities/process-url";
+import { wpdb } from "@/wpdb/wpdb";
+
+const excerptLength = nextpressConfig.excerptLength ?? 55;
+
+/**
+ * Implementation of IPost entity.
+ */
+export class Post implements IPost {
+    constructor(public ID: number) { }
+
+    /** Raw post data from database. */
+    private postData?: Record<string, any>;
+    /** Map of post meta key-value pairs. */
+    private metaMap?: Map<string, string>;
+
+    /**
+     * Retrieves array of Post instances by IDs.
+     *
+     * @param {number[]} ids - Array of post IDs to retrieve.
+     * @returns {Promise<Post[]>} Promise resolving to array of Post instances.
+     */
+    static async get(ids: number[]): Promise<Post[]> {
+        ids = ids.filter(Boolean);
+        if (!ids || !ids.length) return [];
+
+        const postsData = await wpdb
+            .selectFrom('wpPosts')
+            .where('ID', 'in', ids)
+            .selectAll()
+            .execute();
+
+        const metaData = await wpdb
+            .selectFrom('wpPostmeta')
+            .where('postId', 'in', ids)
+            .where('metaKey', 'in', [
+                '_nextpress_path',
+                '_thumbnail_id',
+                '_wp_attachment_image_alt',
+                '_wp_attachment_metadata',
+                '_menu_item_type',
+                '_menu_item_object_id',
+                '_menu_item_url',
+                '_menu_item_menu_item_parent'
+            ])
+            .select(['postId', 'metaKey', 'metaValue'])
+            .execute();
+
+        const metaByPostId = new Map<number, Map<string, string>>();
+        for (const row of metaData) {
+            const postId = Number(row.postId);
+            if (!metaByPostId.has(postId)) {
+                metaByPostId.set(postId, new Map());
+            }
+            metaByPostId.get(postId)?.set(row.metaKey || '', row.metaValue || '');
+        }
+
+        const postDataMap = new Map(postsData.map(post => [Number(post.ID), post]));
+
+        return ids.map(id => {
+            const instance = new Post(id);
+
+            instance.postData = postDataMap.get(id);
+            instance.metaMap = metaByPostId.get(id) || new Map<string, string>();
+
+            postLoader.prime([instance.thumbnailId]);
+
+            return instance;
+        });
+    }
+
+    get path(): string {
+        return this.metaMap?.get('_nextpress_path') ?? '';
+    }
+
+    get thumbnailId(): number {
+        const val = this.metaMap?.get('_thumbnail_id');
+        return val ? Number(val) : 0;
+    }
+
+    private _imageAttributes?: PostImageAttributes;
+    get imageAttributes(): PostImageAttributes {
+        if (this._imageAttributes !== undefined) return this._imageAttributes;
+        if (!this.metaMap) return {};
+
+        const alt = this.metaMap.get('_wp_attachment_image_alt') ?? '';
+        const rawMetadata = this.metaMap.get('_wp_attachment_metadata');
+
+        if (!rawMetadata && !alt) {
+            this._imageAttributes = {};
+            return this._imageAttributes;
+        }
+
+        const guid = this.guid;
+        const index = guid.indexOf('/wp-content');
+        const path = index !== -1 ? guid.slice(index) : guid;
+        const srcPath = `${process.env.WP_SERVICE_URL}${path}`;
+
+        try {
+            const metadata: { height?: string; width?: string } = unserialize(rawMetadata ?? 'a:0:{}');
+            this._imageAttributes = {
+                src: srcPath,
+                alt: alt,
+                height: metadata.height ? Number(metadata.height) : undefined,
+                width: metadata.width ? Number(metadata.width) : undefined
+            };
+        } catch (error: any) {
+            console.warn('Error while getting post: Could not unserialize php: ', error.message);
+            this._imageAttributes = {};
+        }
+
+        return this._imageAttributes;
+    }
+
+    private _menuItemAttributes?: MenuItemAttributes | null
+    get menuItemAttributes(): MenuItemAttributes | null {
+        if (this._menuItemAttributes !== undefined) return this._menuItemAttributes;
+        if (!this.metaMap) return null;
+
+        const typeMeta = this.metaMap.get('_menu_item_type');
+        const type = ['custom', 'post_type', 'taxonomy'].includes(typeMeta ?? '')
+            ? typeMeta as 'custom' | 'post_type' | 'taxonomy'
+            : undefined;
+
+        let url;
+        let objectId;
+        if (type === 'custom') {
+            const urlMeta = this.metaMap.get('_menu_item_url');
+            url = urlMeta ? processURL(urlMeta) : '';
+        } else {
+            objectId = Number(this.metaMap.get('_menu_item_object_id'));
+        }
+
+        const parentId = Number(this.metaMap.get('_menu_item_menu_item_parent')) ?? 0;
+
+        const label = this.postTitle ?? '';
+
+        return {
+            label,
+            type: type ?? 'custom',
+            parentId,
+            objectId: objectId ?? 0,
+            url: url ?? ''
+        }
+    }
+
+    private _postExcerpt?: string
+    get postExcerpt(): string {
+        if (this._postExcerpt !== undefined) return this._postExcerpt;
+        const excerpt = this.postData?.['postExcerpt'] ?? '';
+
+        if (excerpt) return excerpt;
+
+        const postContent = this.postContent;
+        if (!postContent) return '';
+
+        const plainText = postContent
+            .replace(/<[^>]+>/g, ' ') // Strip HTML tags
+            .replace(/\s+/g, ' ')     // Normalize multiple spaces into a single space
+            .trim();
+
+        const words = plainText.split(' ');
+        if (words.length > (excerptLength)) {
+            return words.slice(0, excerptLength).join(' ') + '...';
+        }
+
+        this._postExcerpt = plainText;
+        return this._postExcerpt;
+    }
+
+    get commentCount(): number { return this.postData?.['commentCount'] ?? 0; }
+    get commentStatus(): string { return this.postData?.['commentStatus'] ?? 'closed'; }
+    get guid(): string { return this.postData?.['guid'] ?? ''; }
+    get menuOrder(): number { return this.postData?.['menuOrder'] ?? 0; }
+    get pinged(): string { return this.postData?.['pinged'] ?? ''; }
+    get pingStatus(): string { return this.postData?.['pingStatus'] ?? 'closed'; }
+    get postAuthor(): number { return this.postData?.['postAuthor'] ?? 0; }
+    get postContent(): string { return this.postData?.['postContent'] ?? ''; }
+    get postContentFiltered(): string { return this.postData?.['postContentFiltered'] ?? ''; }
+    get postDate(): Date { return this.postData?.['postDate'] ?? new Date(); }
+    get postDateGmt(): Date { return this.postData?.['postDateGmt'] ?? new Date(); }
+    get postMimeType(): string { return this.postData?.['postMimeType'] ?? ''; }
+    get postModified(): Date { return this.postData?.['postModified'] ?? new Date(); }
+    get postModifiedGmt(): Date { return this.postData?.['postModifiedGmt'] ?? new Date(); }
+    get postName(): string { return this.postData?.['postName'] ?? ''; }
+    get postParent(): number { return this.postData?.['postParent'] ?? 0; }
+    get postPassword(): string { return this.postData?.['postPassword'] ?? ''; }
+    get postStatus(): string { return this.postData?.['postStatus'] ?? 'draft'; }
+    get postTitle(): string { return this.postData?.['postTitle'] ?? ''; }
+    get postType(): string { return this.postData?.['postType'] ?? 'post'; }
+    get toPing(): string { return this.postData?.['toPing'] ?? ''; }
+
+    async getFields(name: string): Promise<Fields> {
+        const meta = await wpdb
+            .selectFrom('wpPostmeta')
+            .where('metaKey', 'like', `${name}%`)
+            .where('postId', '=', this.ID)
+            .select(['metaKey', 'metaValue'])
+            .execute();
+
+        return meta.map(m => ({
+            key: m.metaKey || '',
+            value: m.metaValue || ''
+        }));
+    }
+}

package/lib/entities/term/term.interface.d.ts

@@ -0,0 +1,8 @@
+import { Selectable } from "kysely";
+import { WpTerm, WpTermTaxonomy } from "../../wpdb/wpdb.interface";
+import { IPath } from "../common";
+
+/**
+ * Represents term entity.
+ */
+export interface ITerm extends Selectable<WpTerm>, Selectable<WpTermTaxonomy>, IPath {}