@spoosh/plugin-qs 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @spoosh/plugin-qs
+
+Query string serialization plugin for Spoosh with nested object support.
+
+**[Documentation](https://spoosh.dev/docs/plugins/qs)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`
+
+## Installation
+
+```bash
+npm install @spoosh/plugin-qs
+```
+
+## Usage
+
+```typescript
+import { qsPlugin } from "@spoosh/plugin-qs";
+
+const plugins = [
+  qsPlugin({ arrayFormat: "brackets" }), // default
+];
+
+// Query object
+const query = {
+  pagination: { limit: 10, offset: 0 },
+  filters: { status: "active", tags: ["a", "b"] },
+};
+
+useRead((api) => api.items.$get({ query }));
+// Result: pagination[limit]=10&pagination[offset]=0&filters[status]=active&filters[tags][]=a&filters[tags][]=b
+```
+
+## Features
+
+- ✅ Nested object serialization with bracket notation
+- ✅ Multiple array formats (brackets, indices, repeat, comma)
+- ✅ Dot notation support for nested objects
+- ✅ Automatic null value skipping
+- ✅ Per-request configuration override
+- ✅ Powered by battle-tested `qs` package
+
+## Plugin Config
+
+| Option        | Type                                             | Default      | Description                          |
+| ------------- | ------------------------------------------------ | ------------ | ------------------------------------ |
+| `arrayFormat` | `"brackets" \| "indices" \| "repeat" \| "comma"` | `"brackets"` | How to serialize arrays              |
+| `allowDots`   | `boolean`                                        | `false`      | Use dot notation instead of brackets |
+| `skipNulls`   | `boolean`                                        | `true`       | Skip null values in serialization    |
+| `options`     | `IStringifyOptions`                              | `{}`         | Additional qs stringify options      |
+
+## Per-Request Options
+
+Override plugin defaults for specific requests:
+
+```typescript
+// Use comma-separated arrays for this request
+useRead((api) => api.items.$get({ query }), { arrayFormat: "comma" });
+
+// Use dot notation for nested objects
+useRead((api) => api.search.$get({ query }), { allowDots: true });
+
+// Include null values for this request
+useRead((api) => api.data.$get({ query }), { skipNulls: false });
+```
+
+## Array Formats
+
+### brackets (default)
+
+```typescript
+{ tags: ["a", "b"] }
+// tags[]=a&tags[]=b
+```
+
+### indices
+
+```typescript
+{ tags: ["a", "b"] }
+// tags[0]=a&tags[1]=b
+```
+
+### repeat
+
+```typescript
+{ tags: ["a", "b"] }
+// tags=a&tags=b
+```
+
+### comma
+
+```typescript
+{ tags: ["a", "b"] }
+// tags=a,b
+```
+
+## Dot Notation
+
+```typescript
+// allowDots: false (default)
+{ filters: { status: "active" } }
+// filters[status]=active
+
+// allowDots: true
+{ filters: { status: "active" } }
+// filters.status=active
+```

package/dist/index.d.mts

@@ -0,0 +1,60 @@
+import { IStringifyOptions } from 'qs';
+import { SpooshPlugin } from '@spoosh/core';
+
+interface QsPluginConfig {
+    /** Array format for serialization. Defaults to "brackets". */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Defaults to false. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Defaults to true. */
+    skipNulls?: boolean;
+    /** Additional qs stringify options. */
+    options?: Omit<IStringifyOptions, "arrayFormat" | "allowDots" | "skipNulls">;
+}
+interface QsReadOptions {
+    /** Array format for serialization. Overrides plugin default. */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Overrides plugin default. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Overrides plugin default. */
+    skipNulls?: boolean;
+}
+interface QsWriteOptions {
+    /** Array format for serialization. Overrides plugin default. */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Overrides plugin default. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Overrides plugin default. */
+    skipNulls?: boolean;
+}
+type QsInfiniteReadOptions = QsReadOptions;
+type QsReadResult = object;
+type QsWriteResult = object;
+
+/**
+ * Enables nested object serialization in query parameters using bracket notation.
+ *
+ * Transforms nested objects like `{ pagination: { limit: 10 } }` into
+ * `pagination[limit]=10` format.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/qs | QS Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [qsPlugin({ arrayFormat: "brackets" })];
+ *
+ * // Query: { filters: { status: "active", tags: ["a", "b"] } }
+ * // Result: filters[status]=active&filters[tags][]=a&filters[tags][]=b
+ * ```
+ */
+declare function qsPlugin(config?: QsPluginConfig): SpooshPlugin<{
+    readOptions: QsReadOptions;
+    writeOptions: QsWriteOptions;
+    infiniteReadOptions: QsInfiniteReadOptions;
+    readResult: QsReadResult;
+    writeResult: QsWriteResult;
+}>;
+
+export { type QsInfiniteReadOptions, type QsPluginConfig, type QsReadOptions, type QsReadResult, type QsWriteOptions, type QsWriteResult, qsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { IStringifyOptions } from 'qs';
+import { SpooshPlugin } from '@spoosh/core';
+
+interface QsPluginConfig {
+    /** Array format for serialization. Defaults to "brackets". */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Defaults to false. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Defaults to true. */
+    skipNulls?: boolean;
+    /** Additional qs stringify options. */
+    options?: Omit<IStringifyOptions, "arrayFormat" | "allowDots" | "skipNulls">;
+}
+interface QsReadOptions {
+    /** Array format for serialization. Overrides plugin default. */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Overrides plugin default. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Overrides plugin default. */
+    skipNulls?: boolean;
+}
+interface QsWriteOptions {
+    /** Array format for serialization. Overrides plugin default. */
+    arrayFormat?: "brackets" | "indices" | "repeat" | "comma";
+    /** Use dot notation instead of brackets. Overrides plugin default. */
+    allowDots?: boolean;
+    /** Skip null values in serialization. Overrides plugin default. */
+    skipNulls?: boolean;
+}
+type QsInfiniteReadOptions = QsReadOptions;
+type QsReadResult = object;
+type QsWriteResult = object;
+
+/**
+ * Enables nested object serialization in query parameters using bracket notation.
+ *
+ * Transforms nested objects like `{ pagination: { limit: 10 } }` into
+ * `pagination[limit]=10` format.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/qs | QS Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [qsPlugin({ arrayFormat: "brackets" })];
+ *
+ * // Query: { filters: { status: "active", tags: ["a", "b"] } }
+ * // Result: filters[status]=active&filters[tags][]=a&filters[tags][]=b
+ * ```
+ */
+declare function qsPlugin(config?: QsPluginConfig): SpooshPlugin<{
+    readOptions: QsReadOptions;
+    writeOptions: QsWriteOptions;
+    infiniteReadOptions: QsInfiniteReadOptions;
+    readResult: QsReadResult;
+    writeResult: QsWriteResult;
+}>;
+
+export { type QsInfiniteReadOptions, type QsPluginConfig, type QsReadOptions, type QsReadResult, type QsWriteOptions, type QsWriteResult, qsPlugin };

package/dist/index.js

@@ -0,0 +1,73 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  qsPlugin: () => qsPlugin
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/plugin.ts
+var import_qs = __toESM(require("qs"));
+function qsPlugin(config = {}) {
+  const {
+    arrayFormat: defaultArrayFormat = "brackets",
+    allowDots: defaultAllowDots = false,
+    skipNulls: defaultSkipNulls = true,
+    options: additionalOptions = {}
+  } = config;
+  return {
+    name: "spoosh:qs",
+    operations: ["read", "write", "infiniteRead"],
+    middleware: async (context, next) => {
+      const query = context.requestOptions.query;
+      if (!query || Object.keys(query).length === 0) {
+        return next();
+      }
+      const pluginOptions = context.pluginOptions;
+      const arrayFormat = pluginOptions?.arrayFormat ?? defaultArrayFormat;
+      const allowDots = pluginOptions?.allowDots ?? defaultAllowDots;
+      const skipNulls = pluginOptions?.skipNulls ?? defaultSkipNulls;
+      const stringified = import_qs.default.stringify(query, {
+        ...additionalOptions,
+        arrayFormat,
+        allowDots,
+        skipNulls,
+        encode: false
+      });
+      const flatQuery = import_qs.default.parse(stringified, { depth: 0 });
+      context.requestOptions = {
+        ...context.requestOptions,
+        query: flatQuery
+      };
+      return next();
+    }
+  };
+}

package/dist/index.mjs

@@ -0,0 +1,40 @@
+// src/plugin.ts
+import qs from "qs";
+function qsPlugin(config = {}) {
+  const {
+    arrayFormat: defaultArrayFormat = "brackets",
+    allowDots: defaultAllowDots = false,
+    skipNulls: defaultSkipNulls = true,
+    options: additionalOptions = {}
+  } = config;
+  return {
+    name: "spoosh:qs",
+    operations: ["read", "write", "infiniteRead"],
+    middleware: async (context, next) => {
+      const query = context.requestOptions.query;
+      if (!query || Object.keys(query).length === 0) {
+        return next();
+      }
+      const pluginOptions = context.pluginOptions;
+      const arrayFormat = pluginOptions?.arrayFormat ?? defaultArrayFormat;
+      const allowDots = pluginOptions?.allowDots ?? defaultAllowDots;
+      const skipNulls = pluginOptions?.skipNulls ?? defaultSkipNulls;
+      const stringified = qs.stringify(query, {
+        ...additionalOptions,
+        arrayFormat,
+        allowDots,
+        skipNulls,
+        encode: false
+      });
+      const flatQuery = qs.parse(stringified, { depth: 0 });
+      context.requestOptions = {
+        ...context.requestOptions,
+        query: flatQuery
+      };
+      return next();
+    }
+  };
+}
+export {
+  qsPlugin
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@spoosh/plugin-qs",
+  "version": "0.1.0-beta.0",
+  "description": "Query string serialization plugin for Spoosh with nested object support",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-qs"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/qs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "query-string",
+    "qs",
+    "nested-objects",
+    "api-client"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "qs": "^6.13.0"
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@types/qs": "^6.9.17",
+    "@spoosh/core": "0.1.0-beta.0",
+    "@spoosh/test-utils": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}