@rnaga/wp-node 1.1.2 → 1.1.4

package/README.md

@@ -11,7 +11,7 @@ WP-Node is a Node.js project written in TypeScript that mirrors the WordPress da
 Key benefits include:
 
 - No need to run WordPress PHP
-- Type-safe interaction with WordPress tables (`posts`, `users`, `terms`, etc.)
+- Type-safe interaction with WordPress tables (`posts`, `users`, `terms`, `comments`, `etc.`)
 - Utility classes for querying posts, terms, users, comments, and metadata
 - Supports both Single Site and Multi Site WordPress setups
 - CLI tools to seed databases and run custom commands
@@ -33,20 +33,11 @@ WP-Node is ideal for scenarios where you need direct access to WordPress databas
 - **Debugging or inspecting database records** from a modern TypeScript environment
 - **Creating a web app** (e.g., using Next.js) that needs to pull or push data from a WordPress database, without relying on PHP codebase
 
-## Limitations
-
-**WP-Node Core** is designed specifically to interact with the WordPress database. It does not support traditional WordPress features such as:
-
-- Themes and appearance settings, including updating styling
-- WordPress Template rendering or theming APIs
-- WordPress plugins
-
-Its scope is intentionally limited to providing a type-safe, programmatic interface to WordPress data — not replicating the full behavior of the WordPress runtime.
-
 ## Requirements
 
 - **Node.js** `>=22.0.0`
 - **MySQL** or **MariaDB**
+- **nvm**: Make sure you have [`nvm`](https://github.com/nvm-sh/nvm) command installed on your local machine.
 - Optional: Docker for local WordPress database setup
 
 ## Installation
@@ -69,43 +60,131 @@ docker run -d --name wp --network wpnet -p 8080:80 \
   wordpress
 ```
 
-## Configuration
+Visit http://localhost:8080 in your browser to complete the WordPress setup.
+
+### Initialize WP-Node Project
+
+To get started, create a new folder for your project. This folder will serve as the root directory for your WP-Node application.
+
+```sh
+mkdir wp-node
+cd wp-node
+```
+
+Then, run the command to initialize the project and follow the prompts:
 
-Create your config:
+```sh
+npx @rnaga/wp-node-cli -- init
+```
 
 ```sh
-npx @rnaga/wp-node-cli -- config
+✔ Enter your database hostname: · localhost
+✔ Enter your database port: · 33306
+✔ Enter your database username: · wp
+✔ Enter your database password: · **
+✔ Enter your database name: · wordpress
+✔ Is it a multi-site? · No
+✔ Enter your static assets path: · public
 ```
 
-It will prompt for database settings and generate:
+### Project Structure
+
+After initialization, your project will look like this:
 
 ```
-_wp/
-  └── config/wp.json
-.env
+./
+├── _wp
+│   ├── config
+│   │   ├── index.d.ts
+│   │   └── wp.json
+│   └── settings.ts
+├── .env
+├── index.ts
+├── package-lock.json
+├── package.json
+└── tsconfig.json
 ```
 
-You can configure additional settings such as:
+**Key files**
 
-- `staticAssetsPath`: Path for media references
-- `multisite.enabled`: Enable or disable multisite support
-- Custom post types, taxonomies, statuses
+- `_wp/config/wp.json`: Holds configuration for WP-Node such as public path and multisite info. This file is imported by settings.ts.
+- `_wp/settings.ts`: Initializes the WP-Node Context, including config, database access and hooks.
+- `index.ts`: The main entry point for your WP-Node app. A basic sample is provided.
+- `.env`: Stores sensitive environment variables, including your database credentials and other configuration values required at runtime.
 
-## CLI Usage
+### Run the App
 
-Install CLI tools:
+Once the config is initialized, run the app using:
 
 ```sh
-npm i -S @rnaga/wp-node-cli -- -h
+mvn use 22
+npx ts-node ./index.ts
 ```
 
-Basic command to list posts:
+If everything is working correctly, you’ll see SQL output like:
 
 ```sh
-npx @rnaga/wp-node-cli -- post list
+select * from `wp_posts` as `posts_5` where `posts_5`.`ID` = 1
+[
+  {
+    ID: 1,
+    post_author: 1,
+    post_title: 'Hello world!',
+    ...
+  }
+]
 ```
 
-Develop your own commands using decorators:
+## CLI
+
+WP-Node CLI provides a convenient way to interact with WordPress data without writing any code.
+
+To query a post (e.g. ID = 1), run:
+
+```sh
+npx @rnaga/wp-node-cli -- post get 1 -Z table -F ID,post_title,post_type
+
+┌────────────┬────────────────┐
+│ (index)    │ Values         │
+├────────────┼────────────────┤
+│ ID         │ 1              │
+│ post_title │ 'Hello world!' │
+│ post_type  │ 'post'         │
+└────────────┴────────────────┘
+```
+
+### Listing Available Commands
+
+To view all available CLI commands, run:
+
+```
+npx @rnaga/wp-node-cli -- -h
+```
+
+output:
+
+```sh
+Usage: <command> <subcommand> [options]
+
+Commands:
+   blog             Blog commands
+   comment          Comment commands
+   config           Generate WP config files
+   init             Initialize WP with Node. (Generate wp.json and install dependencies)
+   install          Initialize a new blog and create a user
+   meta             Meta commands (post, comment, blog, term, user, site)
+   option           Options commands
+   post             Post commands
+   repl             Start a REPL
+   role             Role commands
+   site             Site commands
+   term             Term commands
+   user             User commands
+```
+
+### Develop your CLI using decorators:
+
+**Example**:
 
 ```ts
 @command("page", { description: "Page commands" })
@@ -144,6 +223,16 @@ export class Post {
 - **Filter**: Modify data in chainable handlers (similar to `apply_filters`)
 - **Action**: Fire off side effects (`do_action` equivalent)
 
+## Limitations
+
+**WP-Node Core** is designed specifically to interact with the WordPress database. It does not support traditional WordPress features such as:
+
+- Themes and appearance settings, including updating styling
+- WordPress Template rendering or theming APIs
+- WordPress plugins
+
+Its scope is intentionally limited to providing a type-safe, programmatic interface to WordPress data — not replicating the full behavior of the WordPress runtime.
+
 ## Contributing
 
 Feel free to fork, open issues, or suggest improvements. This project is in active development.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rnaga/wp-node",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "",
   "scripts": {
     "build": "rm -rf ./dist && tsc --project tsconfig.build.json && npm run copyfiles && cp package.json ./dist/",

package/types/validating.d.ts

@@ -1,4 +1,5 @@
 import * as val from "../validators";
+import { z } from "zod";
 export type Parser = {
     parse: (v: any, ...args: any) => any;
     safeParse: (v: any, ...args: any) => any;
@@ -6,4 +7,8 @@ export type Parser = {
 export type ParserReturnType<T> = T extends Parser ? ReturnType<T["parse"]> : any;
 export type Tables = keyof typeof val.database.wpTables;
 export type Field<T extends Tables> = keyof (typeof val.database.wpTables)[T]["shape"];
+export type PickZodObjectKey<T extends z.ZodType<any, any, any>, K extends keyof z.infer<T>> = {
+    [P in K]: z.infer<T>[P];
+};
+export type PickZodObjectKeyInArray<T extends z.ZodType<any, any, any>, K extends keyof z.infer<T>[number]> = PickZodObjectKey<T, K>[];
 //# sourceMappingURL=validating.d.ts.map

package/types/validating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validating.d.ts","sourceRoot":"","sources":["../../src/types/validating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,eAAe,CAAC;AAErC,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC9C,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GACtB,GAAG,CAAC;AAER,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACxD,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,MAAM,IAChC,MAAM,CAAC,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"validating.d.ts","sourceRoot":"","sources":["../../src/types/validating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC9C,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GACtB,GAAG,CAAC;AAER,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;AACxD,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,MAAM,IAChC,MAAM,CAAC,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAEnD,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAClC,CAAC,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IACxB;KACD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,CACjC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAClC,CAAC,SAAS,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAChC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC"}

package/validators/helpers.d.ts

@@ -13,4 +13,12 @@ export declare const stringZeroOrOne: z.ZodUnion<[z.ZodDefault<z.ZodOptional<z.Z
 export declare const stringMetaTable: z.ZodEnum<["post", "comment", "blog", "term", "user", "site"]>;
 export declare const userRef: z.ZodEffects<z.ZodString, string | number, string>;
 export declare const blogFlag: z.ZodEnum<["public", "archived", "mature", "spam", "deleted"]>;
+export declare const deepRemoveDefaults: <T>(schema: T) => T;
+export declare const filterRecordByFields: (data: string | Record<string, unknown> | Record<string, unknown>[], fields: string | string[] | undefined) => string | Record<string, any> | Record<string, any>[];
+export declare const recordByField: <T extends z.ZodObject<any, any, any, any, any>>(schema: T, fields: string[]) => z.ZodObject<Record<string, z.ZodTypeAny>, "strip", z.ZodTypeAny, {
+    [x: string]: any;
+}, {
+    [x: string]: any;
+}>;
+export declare const arrayRecordByField: <T extends z.ZodArray<z.ZodObject<any, any, any, any, any>, any>>(schema: T, fields: string[]) => z.ZodArray<any>;
 //# sourceMappingURL=helpers.d.ts.map

package/validators/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/validators/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACvD,SAAS,EAAE,SAAS,CAAC,EAAE,qEAQxB;AAED,eAAO,MAAM,sBAAsB,GAAI,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS,uBAC/B,CAAC;AAEtC,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,uFAQ1C,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,GAAG,OAAO,iIAKlD,CAAC;AAEL,eAAO,MAAM,MAAM,sEAMjB,CAAC;AAEH,eAAO,MAAM,SAAS,4FAGpB,CAAC;AAEH,eAAO,MAAM,SAAS,4FAGpB,CAAC;AAEH,eAAO,MAAM,OAAO,yHAKlB,CAAC;AAEH,eAAO,MAAM,IAAI,2CAKkB,CAAC;AAEpC,eAAO,MAAM,MAAM,qCAAmC,CAAC;AAEvD,eAAO,MAAM,eAAe,0LAQ1B,CAAC;AAEH,eAAO,MAAM,eAAe,gEAO1B,CAAC;AAEH,eAAO,MAAM,OAAO,oDAKlB,CAAC;AAEH,eAAO,MAAM,QAAQ,gEAMnB,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/validators/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACvD,SAAS,EAAE,SAAS,CAAC,EAAE,qEAQxB;AAED,eAAO,MAAM,sBAAsB,GAAI,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS,uBAC/B,CAAC;AAEtC,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,uFAQ1C,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,GAAG,OAAO,iIAKlD,CAAC;AAEL,eAAO,MAAM,MAAM,sEAMjB,CAAC;AAEH,eAAO,MAAM,SAAS,4FAGpB,CAAC;AAEH,eAAO,MAAM,SAAS,4FAGpB,CAAC;AAEH,eAAO,MAAM,OAAO,yHAKlB,CAAC;AAEH,eAAO,MAAM,IAAI,2CAKkB,CAAC;AAEpC,eAAO,MAAM,MAAM,qCAAmC,CAAC;AAEvD,eAAO,MAAM,eAAe,0LAQ1B,CAAC;AAEH,eAAO,MAAM,eAAe,gEAO1B,CAAC;AAEH,eAAO,MAAM,OAAO,oDAKlB,CAAC;AAEH,eAAO,MAAM,QAAQ,gEAMnB,CAAC;AAEH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAAE,QAAQ,CAAC,KAAG,CAgCjD,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClE,QAAQ,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,yDAmDtC,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1E,QAAQ,CAAC,EACT,QAAQ,MAAM,EAAE;;;;EAWjB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,EAE/D,QAAQ,CAAC,EACT,QAAQ,MAAM,EAAE,KACf,CAAC,CAAC,QAAQ,CAAC,GAAG,CAKhB,CAAC"}

package/validators/helpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.blogFlag = exports.userRef = exports.stringMetaTable = exports.stringZeroOrOne = exports.string = exports.path = exports.boolean = exports.stringArr = exports.numberArr = exports.number = exports.booleanWithDefault = exports.numberWithDefault = exports.undefinedIfEmptyString = void 0;
+exports.arrayRecordByField = exports.recordByField = exports.filterRecordByFields = exports.deepRemoveDefaults = exports.blogFlag = exports.userRef = exports.stringMetaTable = exports.stringZeroOrOne = exports.string = exports.path = exports.boolean = exports.stringArr = exports.numberArr = exports.number = exports.booleanWithDefault = exports.numberWithDefault = exports.undefinedIfEmptyString = void 0;
 exports.unionOfLiterals = unionOfLiterals;
 const zod_1 = require("zod");
 // https://github.com/colinhacks/zod/discussions/2790
@@ -84,3 +84,84 @@ exports.blogFlag = zod_1.z.enum([
     "spam",
     "deleted",
 ]);
+const deepRemoveDefaults = (schema) => {
+    if (schema instanceof zod_1.z.ZodDefault)
+        return (0, exports.deepRemoveDefaults)(schema.removeDefault());
+    if (schema instanceof zod_1.z.ZodObject) {
+        const newShape = {};
+        for (const key in schema.shape) {
+            const fieldSchema = schema.shape[key];
+            newShape[key] = zod_1.z.ZodOptional.create((0, exports.deepRemoveDefaults)(fieldSchema));
+        }
+        return new zod_1.z.ZodObject({
+            ...schema._def,
+            shape: () => newShape,
+        });
+    }
+    if (schema instanceof zod_1.z.ZodArray)
+        return zod_1.z.ZodArray.create((0, exports.deepRemoveDefaults)(schema.element));
+    if (schema instanceof zod_1.z.ZodOptional)
+        return zod_1.z.ZodOptional.create((0, exports.deepRemoveDefaults)(schema.unwrap()));
+    if (schema instanceof zod_1.z.ZodNullable)
+        return zod_1.z.ZodNullable.create((0, exports.deepRemoveDefaults)(schema.unwrap()));
+    if (schema instanceof zod_1.z.ZodTuple)
+        return zod_1.z.ZodTuple.create(schema.items.map((item) => (0, exports.deepRemoveDefaults)(item)));
+    return schema;
+};
+exports.deepRemoveDefaults = deepRemoveDefaults;
+const filterRecordByFields = (data, fields) => {
+    // If data is a string, return it as is
+    if (typeof data === "string") {
+        return data;
+    }
+    const fieldsSchema = zod_1.z
+        .string()
+        .optional()
+        .transform((val) => val
+        ? val
+            .split(",")
+            .map((field) => field.trim())
+            .filter((field) => field.length > 0)
+        : []);
+    const parsedFields = fieldsSchema.parse(Array.isArray(fields) ? fields.join(",") : fields);
+    // If fields are specified, filter the result data
+    if (0 == parsedFields.length) {
+        return data;
+    }
+    const filterObject = (record) => {
+        const filteredRecord = {};
+        parsedFields.forEach((field) => {
+            if (field in record) {
+                filteredRecord[field] = record[field];
+            }
+        });
+        return filteredRecord;
+    };
+    // If data is an object, filter it
+    if (typeof data === "object" && !Array.isArray(data)) {
+        return filterObject(data);
+    }
+    // If data is an array, filter each item
+    if (Array.isArray(data)) {
+        return data.map((item) => filterObject(item));
+    }
+    return data;
+};
+exports.filterRecordByFields = filterRecordByFields;
+const recordByField = (schema, fields) => {
+    // Filter the schema to only include the specified fields
+    const filteredShape = {};
+    for (const field of fields) {
+        if (field in schema.shape) {
+            filteredShape[field] = schema.shape[field];
+        }
+    }
+    return zod_1.z.object(filteredShape);
+};
+exports.recordByField = recordByField;
+const arrayRecordByField = (schema, fields) => {
+    // Filter the schema to only include the specified fields
+    const filteredShape = (0, exports.recordByField)(schema.element, fields);
+    return zod_1.z.array(filteredShape);
+};
+exports.arrayRecordByField = arrayRecordByField;