nextpress-core 1.0.2 → 1.1.0

package/dist/acf-functions/types/acf-field.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,19 @@
+import { ACFField, NextpressField } from "./acf-field";
+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 */
+export type NextpressLayout = TransformACFLayout<ACFLayout>;
+/**
+ * Represents a layout within an ACF Flexible Content field.
+ */
+export type ACFLayout = {
+    key: string;
+    name: string;
+    label: string;
+    display: 'table' | 'block' | 'row';
+    sub_fields: ACFField[];
+    min?: string;
+    max?: string;
+};
+export {};

package/dist/acf-functions/types/acf-layout.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/acf-functions/types/acf-values.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,196 @@
+import { IPost } from "@/entities/post/post.interface";
+import { ITerm } from "@/entities/term/term.interface";
+import { IUser } from "@/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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+export type ACFIconObject = {
+    type: string;
+    value: string;
+};
+export type ACFLinkObject = {
+    title: string;
+    url: string;
+    target: string;
+};
+export type ACFChoiceObject = {
+    label?: string;
+    value?: string;
+};
+export 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;
+};
+export {};

package/dist/acf-functions/types/components/field-props.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/acf-functions/types/components/nextpress-component.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/common.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Represents entity with a path.
+ */
+export interface IPath {
+    /** Nextpress path to entity. */
+    path: string;
+}
+/**
+ * Array of field key-value pairs.
+ */
+export 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/dist/entities/common.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/index.d.ts

@@ -0,0 +1,9 @@
+export * from './common';
+export * from './post/post.interface';
+export * from './post/post';
+export * from './user/user';
+export * from './user/user.interface';
+export * from './term/term.interface';
+export * from './term/term';
+export * from './option/option.interface';
+export * from './option/option';

package/dist/entities/index.js

@@ -0,0 +1,9 @@
+export * from './common';
+export * from './post/post.interface';
+export * from './post/post';
+export * from './user/user';
+export * from './user/user.interface';
+export * from './term/term.interface';
+export * from './term/term';
+export * from './option/option.interface';
+export * from './option/option';

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

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

package/dist/entities/option/option.interface.js

@@ -0,0 +1,2 @@
+;
+export {};

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

@@ -0,0 +1,67 @@
+import { Selectable } from "kysely";
+import { WpPost } from "../../wpdb/wpdb.interface";
+import { IFieldLocation, IPath } from "../common";
+/**
+ * Attributes for post attachment images.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface IBasePost extends Selectable<WpPost> {
+}
+/**
+ * Page post properties.
+ */
+export interface IPagePost extends IBasePost, IPath {
+}
+/**
+ * Standard post properties.
+ */
+export interface IPostPost extends IBasePost, IPath {
+    /** Featured image attachment ID. */
+    thumbnailId: number;
+}
+/**
+ * Attachment post properties.
+ */
+export interface IAttachmentPost extends IBasePost {
+    /** Image attributes. */
+    imageAttributes: PostImageAttributes;
+}
+/**
+ * Menu item properties.
+ */
+export interface IMenuItem extends IBasePost {
+    /** Menu item attributes. */
+    menuItemAttributes: MenuItemAttributes | null;
+}
+/**
+ * Comprehensive post entity encompassing all post types.
+ */
+export interface IPost extends IBasePost, IPagePost, IPostPost, IAttachmentPost, IMenuItem, IFieldLocation {
+}

package/dist/entities/post/post.interface.js

@@ -0,0 +1,2 @@
+;
+export {};

package/dist/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 {
+}

package/dist/entities/term/term.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/entities/user/user.interface.d.ts

@@ -0,0 +1,9 @@
+import { Selectable } from "kysely";
+import { WpUser } from "../../wpdb/wpdb.interface";
+/**
+ * Represents user entity.
+ */
+export interface IUser extends Selectable<WpUser> {
+    roles: string[];
+    showAdminBar: boolean;
+}

package/dist/entities/user/user.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/globals/entity-loader/entity-loader-base.d.ts

@@ -1,4 +1,4 @@
-import { EntityLoader, EntityQuery } from "./entity-loader";
+import { EntityLoader, EntityQuery } from "./entity-loader.interface";
 /**
  * Constructor type for entity queries.
  */

package/dist/globals/entity-loader/entity-loader.interface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Defines the contract for an entity loader.
+ *
+ * @template EntityT The type of entity being loaded.
+ * @template QueryArgsT The type of arguments used for querying the entity.
+ */
+export interface EntityLoader<EntityT, QueryArgsT> {
+    /**
+     * Queues entity IDs for loading.
+     *
+     * @param {number[]} ids Array of entity IDs.
+     */
+    prime: (ids: number[]) => void;
+    /**
+     * Finds entity IDs based on query arguments and queues them for loading.
+     *
+     * @param {QueryArgsT} args Query arguments.
+     * @returns {Promise<{ids: number[], count: number}>} Array of found IDs and the total count.
+     * @throws {Error} If the query fails.
+     */
+    findAndPrime: (args: QueryArgsT) => Promise<{
+        ids: number[];
+        count: number;
+    }>;
+    /**
+     * Retrieves entities by their IDs.
+     *
+     * @param {number[]} ids Array of entity IDs.
+     * @returns {Promise<EntityT[]>} Array of entities.
+     * @throws {Error} If retrieval fails.
+     */
+    get: (ids: number[]) => Promise<EntityT[]>;
+}
+/**
+ * Defines the contract for an entity query.
+ *
+ * @template TArgs The type of query arguments.
+ */
+export interface EntityQuery<TArgs> {
+    /**
+     * Executes the query and returns the matching entity IDs.
+     *
+     * @returns {Promise<number[]>} Array of entity IDs.
+     * @throws {Error} If the query fails.
+     */
+    getIds(): Promise<number[]>;
+    /**
+     * Retrieves the total count of entities matching the query.
+     * @returns {number | undefined} Total count, or undefined if not computed.
+     */
+    getCount(): number | undefined;
+}

package/dist/globals/entity-loader/entity-loader.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/globals/entity-loader/option-loader.d.ts

@@ -1,6 +1,6 @@
 import { IOption } from "../../entities/option/option.interface";
 import { OptionQueryArgs } from "../../repository/optionquery/option-query-args";
-import { EntityLoader } from "./entity-loader";
+import { EntityLoader } from "./entity-loader.interface";
 declare global {
     /** Global instance of the OptionLoader. */
     var optionLoader: EntityLoader<IOption, OptionQueryArgs>;

package/dist/globals/entity-loader/post-loader.d.ts

@@ -1,5 +1,5 @@
 import { IPost } from "../../entities/post/post.interface";
-import { EntityLoader } from "./entity-loader";
+import { EntityLoader } from "./entity-loader.interface";
 declare global {
     /** Global instance of the PostLoader. */
     var postLoader: EntityLoader<IPost, PostQueryArgs>;

package/dist/globals/entity-loader/term-loader.d.ts

@@ -1,5 +1,5 @@
 import { ITerm } from "../../entities/term/term.interface";
-import { EntityLoader } from "./entity-loader";
+import { EntityLoader } from "./entity-loader.interface";
 declare global {
     /** Global instance of the TermLoader. */
     var termLoader: EntityLoader<ITerm, TermQueryArgs>;

package/dist/globals/entity-loader/user-loader.d.ts

@@ -1,5 +1,5 @@
 import { IUser } from "../../entities/user/user.interface";
-import { EntityLoader } from "./entity-loader";
+import { EntityLoader } from "./entity-loader.interface";
 declare global {
     /** Global instance of the UserLoader. */
     var userLoader: EntityLoader<IUser, UserQueryArgs>;

package/dist/globals/get-field/get-field.d.ts

@@ -1,5 +1,6 @@
+import { NextpressFieldGroup } from "@/acf-functions/types/acf-field-group";
+import { FieldProps } from "@/acf-functions/types/components/field-props";
 import { IFieldLocation } from "../../entities/common";
-import { FieldProps } from "../../acf-functions/types/components/field-props";
 /** Specifies location to retrieve fields from. */
 type Location = IFieldLocation | 'options';
 declare global {

package/dist/globals/index.d.ts

@@ -0,0 +1,10 @@
+export * from './globals';
+export * from './nextpress-config/nextpress-config';
+export * from './get-field/get-field';
+export * from './queried-object/queried-object';
+export * from './entity-loader/entity-loader-base';
+export * from './entity-loader/option-loader';
+export * from './entity-loader/user-loader';
+export * from './entity-loader/post-loader';
+export * from './entity-loader/term-loader';
+export * from './entity-loader/entity-loader.interface';

package/dist/globals/index.js

@@ -0,0 +1,10 @@
+export * from './globals';
+export * from './nextpress-config/nextpress-config';
+export * from './get-field/get-field';
+export * from './queried-object/queried-object';
+export * from './entity-loader/entity-loader-base';
+export * from './entity-loader/option-loader';
+export * from './entity-loader/user-loader';
+export * from './entity-loader/post-loader';
+export * from './entity-loader/term-loader';
+export * from './entity-loader/entity-loader.interface';

package/dist/globals/nextpress-config/nextpress-config.interface.d.ts

@@ -0,0 +1,14 @@
+type NextpressConfig = {
+    /** Custom taxonomies used to categorize and group content (like categories or tags). Expects the taxonomy's URL prefix, so tag instead of post_tag */
+    readonly publicTaxonomies?: string[];
+    /** Custom post types registered for public consumption (like posts, pages, or portfolio). */
+    readonly publicPostTypes?: string[];
+    /** Post types that should display archive pages on the frontend. */
+    readonly archivedPostTypes?: string[];
+    /** The word/character count limit for automatically generated post teasers. */
+    readonly excerptLength?: number;
+    /** Database option keys (from wp_options) to fetch early for performance optimization. */
+    readonly preLoadOptions?: string[];
+} & {
+    [key: string]: any;
+};

package/dist/globals/nextpress-config/nextpress-config.interface.js

@@ -0,0 +1 @@
+"use strict";

package/dist/repository/index.d.ts

@@ -0,0 +1,5 @@
+export * from './userquery/user-query';
+export * from './termquery/term-query';
+export * from './optionquery/option-query';
+export * from './optionquery/option-query-args';
+export * from './postquery/post-query';

package/dist/repository/index.js

@@ -0,0 +1,5 @@
+export * from './userquery/user-query';
+export * from './termquery/term-query';
+export * from './optionquery/option-query';
+export * from './optionquery/option-query-args';
+export * from './postquery/post-query';

package/dist/repository/optionquery/option-query-args.d.ts

@@ -0,0 +1,19 @@
+import { DB } from "@/wpdb/wpdb.interface";
+import { ComparisonOperatorExpression, ReferenceExpression } from "kysely";
+/**
+ * Defines the arguments for querying options.
+ */
+export interface OptionQueryArgs {
+    /**
+     * Database column reference to query against.
+     */
+    column: ReferenceExpression<DB, "wpOptions">;
+    /**
+     * Comparison operator for the query.
+     */
+    operand?: ComparisonOperatorExpression;
+    /**
+     * Value or array of values to compare.
+     */
+    value: string | string[];
+}

package/dist/repository/optionquery/option-query-args.js

@@ -0,0 +1 @@
+export {};

package/dist/repository/optionquery/option-query.d.ts

@@ -1,4 +1,4 @@
-import { EntityQuery } from "../../globals/entity-loader/entity-loader";
+import { EntityQuery } from "../../globals/entity-loader/entity-loader.interface";
 import { OptionQueryArgs } from "./option-query-args";
 import { IOption } from "../../entities/option/option.interface";
 /**