nextpress-core 1.0.0

package/lib/entities/term/term.ts

@@ -0,0 +1,82 @@
+import { wpdb } from "@/wpdb/wpdb";
+import { ITerm } from "./term.interface";
+
+/**
+ * Implementation of ITerm entity.
+ */
+export class Term implements ITerm
+{
+    constructor(
+        public termId: number
+    ) {}
+
+    /** Raw term data from database. */
+    private termData?: Record<string, any>;
+    /** Map of term meta key-value pairs. */
+    private metaMap?: Map<string, string>;
+
+    /**
+     * Retrieves array of Term instances by IDs.
+     *
+     * @param {number[]} ids - Array of term IDs to retrieve.
+     * @returns {Promise<Term[]>} Promise resolving to array of Term instances.
+     */
+    static async get(ids: number[]): Promise<Term[]> {
+        ids = ids.filter(Boolean);
+        if (!ids || !ids.length) return [];
+
+        const combinedData = await wpdb
+            .selectFrom('wpTerms as term')
+            .innerJoin('wpTermTaxonomy as taxonomy', 'term.termId', 'taxonomy.termId')
+            .where('term.termId', 'in', ids)
+            .select([
+                'term.termId as termId',
+                'term.name as name',
+                'term.slug as slug',
+                'term.termGroup as termGroup',
+                'taxonomy.termTaxonomyId as termTaxonomyId',
+                'taxonomy.taxonomy as taxonomy',
+                'taxonomy.description as description',
+                'taxonomy.parent as parent',
+                'taxonomy.count as count'
+            ])
+            .execute();
+
+        const metaData = await wpdb
+            .selectFrom('wpTermmeta')
+            .where('termId', 'in', ids)
+            .where('metaKey', '=', '_nextpress_path')
+            .select(['termId', 'metaKey', 'metaValue'])
+            .execute();
+
+        const metaByTermId = new Map<number, Map<string, string>>();
+        for (const row of metaData) {
+            const termId = Number(row.termId);
+            if (!metaByTermId.has(termId)) {
+                metaByTermId.set(termId, new Map());
+            }
+            metaByTermId.get(termId)?.set(row.metaKey || '', row.metaValue || '');
+        }
+
+        const combinedDataMap = new Map(combinedData.map(row => [Number(row.termId), row]));
+
+        return ids.map(id => {
+            const instance = new Term(id);
+
+            instance.termData = combinedDataMap.get(id);
+            instance.metaMap = metaByTermId.get(id) || new Map<string, string>();
+
+            return instance;
+        });
+    }
+
+    get path(): string { return this.metaMap?.get('_nextpress_path') ?? ''; }
+    get name(): string { return this.termData?.['name'] ?? ''; }
+    get slug(): string { return this.termData?.['slug'] ?? ''; }
+    get termGroup(): number { return this.termData?.['termGroup'] ? Number(this.termData['termGroup']) : 0; }
+    get parent(): number { return this.termData?.['parent'] ? Number(this.termData['parent']) : 0; }
+    get description(): string { return this.termData?.['description'] ?? ''; }
+    get termTaxonomyId(): number { return this.termData?.['termTaxonomyId'] ? Number(this.termData['termTaxonomyId']) : 0; }
+    get count(): number { return this.termData?.['count'] ? Number(this.termData['count']) : 0; }
+    get taxonomy(): string { return this.termData?.['taxonomy'] ?? ''; }
+}

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

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

package/lib/entities/user/user.ts

@@ -0,0 +1,86 @@
+import { unserialize } from "php-serialize";
+import { IUser } from "./user.interface";
+import { wpdb } from "@/wpdb/wpdb";
+
+export class User implements IUser {
+    constructor(
+        public ID: number
+    ) {}
+
+    /** Raw user data from database. */
+    private userData?: Record<string, any>;
+    /** Map of user meta key-value pairs. */
+    private metaMap?: Map<string, string>;
+
+    /**
+     * Retrieves array of User instances by IDs.
+     *
+     * @param {number[]} ids - Array of user IDs to retrieve.
+     * @returns {Promise<User[]>} Promise resolving to array of User instances.
+     */
+    static async get(ids: number[]): Promise<User[]> {
+        ids = ids.filter(Boolean);
+        if (!ids || !ids.length) return [];
+
+        const usersData = await wpdb
+            .selectFrom('wpUsers')
+            .where('ID', 'in', ids)
+            .selectAll()
+            .execute();
+
+        const metaData = await wpdb
+            .selectFrom('wpUsermeta')
+            .where('userId', 'in', ids)
+            .where('metaKey', 'in', [
+                'wp_capabilities',
+                'show_admin_bar_front'
+            ])
+            .select(['userId', 'metaKey', 'metaValue'])
+            .execute();
+
+        const metaByUserId = new Map<number, Map<string, string>>();
+        for (const row of metaData) {
+            const userId = Number(row.userId);
+            if (!metaByUserId.has(userId)) {
+                metaByUserId.set(userId, new Map());
+            }
+            metaByUserId.get(userId)?.set(row.metaKey || '', row.metaValue || '');
+        }
+
+        const userDataMap = new Map(usersData.map(user => [Number(user.ID), user]));
+
+        return ids.map(id => {
+            const instance = new User(id);
+
+            instance.userData = userDataMap.get(id);
+            instance.metaMap = metaByUserId.get(id) || new Map<string, string>();
+
+            return instance;
+        });
+    }
+
+    get roles(): string[] {
+        const rawCapabilities = this.metaMap?.get('wp_capabilities');
+        if (!rawCapabilities) return [];
+        try {
+            return Object.keys(unserialize(rawCapabilities));
+        } catch (error: any) {
+            console.warn('Error while getting user: Could not unserialize php: ', error.message);
+            return [];
+        }
+    }
+
+    get showAdminBar(): boolean {
+        return this.metaMap?.get('show_admin_bar_front') === 'true';
+    }
+
+    get displayName(): string { return this.userData?.['displayName'] ?? ''; }
+    get userActivationKey(): string { return this.userData?.['userActivationKey'] ?? ''; }
+    get userEmail(): string { return this.userData?.['userEmail'] ?? ''; }
+    get userLogin(): string { return this.userData?.['userLogin'] ?? ''; }
+    get userNicename(): string { return this.userData?.['userNicename'] ?? ''; }
+    get userPass(): string { return this.userData?.['userPass'] ?? ''; }
+    get userRegistered(): Date { return this.userData?.['userRegistered'] ?? new Date(); }
+    get userStatus(): number { return this.userData?.['userStatus'] ? Number(this.userData['userStatus']) : 0; }
+    get userUrl(): string { return this.userData?.['userUrl'] ?? ''; }
+}

package/lib/globals/entity-loader/entity-loader-base.ts

@@ -0,0 +1,141 @@
+import { EntityLoader, EntityQuery } from "./entity-loader";
+import { queriedObjectState } from "../globals";
+
+/**
+ * Constructor type for entity queries.
+ */
+type QueryConstructor<TArgs> = new (args: TArgs) => EntityQuery<TArgs>;
+
+export interface ILoaderStorage<TEntity> {
+    loadQueue: Set<number>;
+    entityCache: Map<number, TEntity>;
+    promisedEntities: Map<number, Promise<TEntity[]>>;
+}
+
+export abstract class EntityLoaderBase<TEntity, TArgs> implements EntityLoader<TEntity, TArgs>
+{
+    /** Query class used to fetch entity IDs. */
+    protected abstract queryClass: QueryConstructor<TArgs>;
+
+    /**
+     * Fetches entities from the database by ID.
+     *
+     * @param {number[]} ids Array of entity IDs.
+     *
+     * @returns {Promise<TEntity[]>} Array of fetched entities.
+     * @throws {Error} If database fetch fails.
+     */
+    protected abstract fetchFromDatabase(ids: number[]): Promise<TEntity[]>;
+
+    /**
+     * Gets the ID of an entity.
+     *
+     * @param {TEntity} entity The entity.
+     *
+     * @returns {number} The entity ID.
+     */
+    protected abstract getEntityId(entity: TEntity): number;
+
+    /**
+     * Retrieves the local state for the loader from the global cache.
+     *
+     * @returns {ILoaderStorage<TEntity>} The loader storage.
+     */
+    private getLocalState(): ILoaderStorage<TEntity> {
+        const state = queriedObjectState();
+        const loaderKey = `__loader_${this.constructor.name}`;
+
+        if (!state.loaderStates[loaderKey]) {
+            state.loaderStates[loaderKey] = {
+                loadQueue: new Set(),
+                entityCache: new Map(),
+                promisedEntities: new Map()
+            };
+        }
+        return state.loaderStates[loaderKey];
+    }
+
+    /**
+     * Adds IDs to the loading queue.
+     *
+     * @param {number[]} ids Array of IDs to prime.
+     */
+    public prime(ids: number[]): void {
+        const state = this.getLocalState();
+        for (const id of ids) {
+            if (state.loadQueue.has(id) || state.entityCache.has(id) || state.promisedEntities.has(id)) {
+                continue;
+            }
+            state.loadQueue.add(id);
+        }
+    }
+
+    /**
+     * Finds entity IDs matching the arguments and queues them for loading.
+     *
+     * @param {TArgs} args Query arguments.
+     *
+     * @returns {Promise<{ ids: number[]; count: number }>} Matching IDs and total count.
+     * @throws {Error} If query execution fails.
+     */
+    public async findAndPrime(args: TArgs): Promise<{ ids: number[]; count: number }> {
+        const query = new this.queryClass(args);
+
+        const ids = await query.getIds();
+        const count = query.getCount() ?? ids.length;
+
+        this.get(ids);
+
+        return { ids, count };
+    }
+
+    /**
+     * Retrieves entities by ID.
+     *
+     * @param {number[]} ids Array of entity IDs.
+     *
+     * @returns {Promise<TEntity[]>} Array of entities.
+     * @throws {Error} If entity fetching fails.
+     */
+    public async get(ids: number[]): Promise<TEntity[]> {
+        const state = this.getLocalState();
+
+        const newIds = ids.filter(id => !state.entityCache.has(id) && !state.promisedEntities.has(id));
+
+        if (newIds.length > 0) {
+            this.prime(newIds);
+        }
+
+        if (state.loadQueue.size > 0) {
+            const queue = Array.from(state.loadQueue);
+            state.loadQueue.clear();
+
+            const fetchPromise = this.fetchFromDatabase(queue).then(queuedEntities => {
+                queuedEntities.forEach(entity => state.entityCache.set(this.getEntityId(entity), entity));
+                queue.forEach(id => state.promisedEntities.delete(id));
+                return queuedEntities;
+            });
+
+            queue.forEach(id => {
+                state.promisedEntities.set(id, fetchPromise);
+            });
+        }
+
+        const activePromises = Array.from(
+            new Set(
+                ids
+                    .map(id => state.promisedEntities.get(id))
+                    .filter((p): p is Promise<TEntity[]> => !!p)
+            )
+        );
+
+        if (activePromises.length > 0) {
+            await Promise.all(activePromises);
+        }
+
+        return ids.flatMap(id => {
+            const entity = state.entityCache.get(id);
+            return entity ? [entity] : [];
+        });
+    }
+}

package/lib/globals/entity-loader/entity-loader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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/lib/globals/entity-loader/option-loader.ts

@@ -0,0 +1,56 @@
+import { OptionQuery } from "@/repository/optionquery/option-query";
+import { Option } from "../../entities/option/option";
+import { IOption } from "../../entities/option/option.interface";
+import { OptionQueryArgs } from "../../repository/optionquery/option-query-args";
+import { EntityLoader } from "./entity-loader";
+import { EntityLoaderBase } from "./entity-loader-base";
+
+class OptionLoader extends EntityLoaderBase<IOption, OptionQueryArgs> {
+    private static _instance: OptionLoader;
+
+    protected queryClass = OptionQuery;
+
+    private constructor() {
+        super();
+    }
+
+    public static instance(): OptionLoader {
+        if (!this._instance) {
+            this._instance = new OptionLoader();
+        }
+        return this._instance;
+    }
+
+    protected async fetchFromDatabase(ids: number[]): Promise<IOption[]> {
+        return await Option.get(ids);
+    }
+
+    protected getEntityId(option: IOption): number {
+        return option.optionId;
+    }
+}
+
+declare global {
+    /** Global instance of the OptionLoader. */
+    var optionLoader: EntityLoader<IOption, OptionQueryArgs>
+
+    /**
+     * Retrieves an option value by name.
+     *
+     * @param {string} name The option name.
+     *
+     * @returns {Promise<string | undefined>} The option value or undefined.
+     */
+    var getOption: (name: string) => Promise<string | undefined>;
+}
+
+globalThis.optionLoader = OptionLoader.instance();
+globalThis.getOption = async (name) => {
+    const foundOptions = await optionLoader.findAndPrime({
+        column: 'optionName',
+        operand: '=',
+        value: name
+    })
+
+    return (await optionLoader.get(foundOptions.ids))[0]?.optionValue;
+}

package/lib/globals/entity-loader/post-loader.ts

@@ -0,0 +1,59 @@
+import { Post } from "@/entities/post/post";
+import { IPost } from "../../entities/post/post.interface";
+import { EntityLoader } from "./entity-loader";
+import { EntityLoaderBase } from "./entity-loader-base";
+import { PostQuery } from "@/repository/postquery/post-query";
+
+class PostLoader extends EntityLoaderBase<IPost, PostQueryArgs> {
+    private static _instance: PostLoader;
+
+    protected queryClass = PostQuery;
+
+    private constructor() {
+        super();
+    }
+
+    public static instance(): PostLoader {
+        if (!this._instance) {
+            this._instance = new PostLoader();
+        }
+        return this._instance;
+    }
+
+    protected async fetchFromDatabase(ids: number[]): Promise<IPost[]> {
+        return await Post.get(ids);
+    }
+
+    protected getEntityId(post: IPost): number {
+        return post.ID;
+    }
+}
+
+declare global {
+    /** Global instance of the PostLoader. */
+    var postLoader: EntityLoader<IPost, PostQueryArgs>
+    /**
+     * Retrieves posts by their IDs.
+     *
+     * @param {number[]} ids Array of post IDs.
+     * @returns {Promise<IPost[]>} Array of posts.
+     */
+    var getPosts: (ids: number[]) => Promise<IPost[]>
+    /**
+     * Retrieves a single post by ID.
+     *
+     * @param {number} id The post ID.
+     * @returns {Promise<IPost | undefined>} The post or undefined.
+     */
+    var getPost: (id: number) => Promise<IPost | undefined>
+}
+
+globalThis.postLoader = PostLoader.instance();
+globalThis.getPosts = async (ids) => {
+    return await postLoader.get(ids);
+}
+globalThis.getPost = async (id) => {
+    return (await postLoader.get([id]))[0];
+}
+
+export {};

package/lib/globals/entity-loader/term-loader.ts

@@ -0,0 +1,59 @@
+import { Term } from "@/entities/term/term";
+import { ITerm } from "../../entities/term/term.interface";
+import { EntityLoader } from "./entity-loader";
+import { EntityLoaderBase } from "./entity-loader-base";
+import { TermQuery } from "@/repository/termquery/term-query";
+
+class TermLoader extends EntityLoaderBase<ITerm, TermQueryArgs> {
+    private static _instance: TermLoader;
+
+    protected queryClass = TermQuery;
+
+    private constructor() {
+        super();
+    }
+
+    public static instance(): TermLoader {
+        if (!this._instance) {
+            this._instance = new TermLoader();
+        }
+        return this._instance;
+    }
+
+    protected async fetchFromDatabase(ids: number[]): Promise<ITerm[]> {
+        return await Term.get(ids);
+    }
+
+    protected getEntityId(term: ITerm): number {
+        return term.termId;
+    }
+}
+
+declare global {
+    /** Global instance of the TermLoader. */
+    var termLoader: EntityLoader<ITerm, TermQueryArgs>
+    /**
+     * Retrieves terms by their IDs.
+     *
+     * @param {number[]} ids Array of term IDs.
+     * @returns {Promise<ITerm[]>} Array of terms.
+     */
+    var getTerms: (ids: number[]) => Promise<ITerm[]>
+    /**
+     * Retrieves a single term by ID.
+     *
+     * @param {number} id The term ID.
+     * @returns {Promise<ITerm | undefined>} The term or undefined.
+     */
+    var getTerm: (id: number) => Promise<ITerm | undefined>
+}
+
+globalThis.termLoader = TermLoader.instance();
+globalThis.getTerms = async (ids) => {
+    return await termLoader.get(ids);
+}
+globalThis.getTerm = async (id) => {
+    return (await termLoader.get([id]))[0];
+}
+
+export {};

package/lib/globals/entity-loader/user-loader.ts

@@ -0,0 +1,60 @@
+import { User } from "@/entities/user/user";
+import { IUser } from "../../entities/user/user.interface";
+import { EntityLoader } from "./entity-loader";
+import { EntityLoaderBase } from "./entity-loader-base";
+import { UserQuery } from "@/repository/userquery/user-query";
+
+class UserLoader extends EntityLoaderBase<IUser, UserQueryArgs> {
+    private static _instance: UserLoader;
+
+    protected queryClass = UserQuery;
+
+    private constructor() {
+        super();
+    }
+
+    public static instance(): UserLoader {
+        if (!this._instance) {
+            this._instance = new UserLoader();
+        }
+        return this._instance;
+    }
+
+    protected async fetchFromDatabase(ids: number[]): Promise<IUser[]> {
+        return await User.get(ids);
+    }
+
+    protected getEntityId(user: IUser): number {
+        return user.ID;
+    }
+}
+
+declare global {
+    /** Global instance of the UserLoader. */
+    var userLoader: EntityLoader<IUser, UserQueryArgs>
+    /**
+     * Retrieves users by their IDs.
+     *
+     * @param {number[]} ids Array of user IDs.
+     * @returns {Promise<IUser[]>} Array of users.
+     */
+    var getUsers: (ids: number[]) => Promise<IUser[]>
+
+    /**
+     * Retrieves a single user by ID.
+     *
+     * @param {number} id The user ID.
+     * @returns {Promise<IUser | undefined>} The user or undefined.
+     */
+    var getUser: (id: number) => Promise<IUser | undefined>
+}
+
+globalThis.userLoader = UserLoader.instance();
+globalThis.getUsers = async (ids) => {
+    return await userLoader.get(ids);
+}
+globalThis.getUser = async (id) => {
+    return (await userLoader.get([id]))[0];
+}
+
+export {};

package/lib/globals/get-field/get-field.ts

@@ -0,0 +1,75 @@
+import { mapField } from "../../acf-functions/services/map-fields/map-fields";
+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 {
+    /**
+     * Retrieves, parses, and maps an Advanced Custom Fields (ACF) value to its corresponding component properties.
+     *
+     * @param {T} fieldGroup The configuration object defining the ACF field group and its schema.
+     * @param {K} selector The key name of the field to retrieve.
+     * @param {Location} [location] The database entity or context from which to load the field data. Accepts an `IFieldLocation` object or the string `'options'`. Defaults to the current queried object if omitted.
+     *
+     * @returns {Promise<FieldProps<T>[K]>} A promise resolving to the mapped field properties.
+     */
+    var getField: <
+        T extends NextpressFieldGroup,
+        K extends keyof FieldProps<T> & string
+    >(
+        fieldGroup: T,
+        selector: K,
+        location?: Location
+    ) => Promise<FieldProps<T>[K]>;
+}
+
+globalThis.getField = async (fieldGroup, selector, location) => {
+    if (!location) {
+        switch(queriedObject.objectType) {
+            case 'post':
+                location = await getThePost();
+                break;
+            // TODO: Add support for Term and User
+            // case 'term':
+            //     location = await getTheTerm();
+            //     break;
+            // case 'user':
+            //     location = await getTheUser();
+            //     break;
+        }
+    }
+    if (!location) return [];
+
+    const values = await (async () => {
+        if (location === 'options') {
+            const prefix = 'options_';
+
+            const foundOptions = await optionLoader.findAndPrime({
+                column: 'optionName',
+                operand: 'like',
+                value: `${prefix}%`
+            })
+
+            const options = await optionLoader.get(foundOptions.ids);
+
+            return options.map(option => ({
+                key: option.optionName.slice(prefix.length),
+                value: option.optionValue
+            }))
+        }
+
+        return await location.getFields(selector);
+    })() ?? [];
+
+    const valueMap: Map<string, string> = values.reduce((map, value) => {
+        map.set(value.key, value.value);
+        return map;
+    }, new Map());
+
+    const field = fieldGroup.fields.find(field => field.name === selector);
+    if (!field) return;
+
+    return mapField(field, valueMap) as any;
+}