use-l5 0.0.1

package/README.md

@@ -0,0 +1,117 @@
+# use-l5
+
+Nuxt-модуль с типизированным `useL5`-композаблом для парсинга фильтров, синхронизации с query в роуте и сборки параметров для API/URL.
+
+## Возможности
+
+- типизированная схема фильтров на основе конструкторов `String/Number/Boolean`
+- двусторонняя синхронизация с `route.query` (опционально)
+- генерация параметров для API и URL
+- базовые параметры пагинации и сортировки
+
+## Установка
+
+```bash
+npx nuxi module add use-l5
+```
+
+или
+
+```bash
+pnpm add use-l5
+```
+
+## Настройка модуля
+
+`nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['use-l5'],
+  useL5: {
+    syncWithRoute: true,
+    urlUpdateStrategy: 'replace',
+    boolToNumber: true
+  }
+})
+```
+
+## Базовое использование
+
+```ts
+import { useL5 } from '#imports'
+
+const schema = {
+  q: String,
+  category: [String],
+  inStock: Boolean,
+  price: Number
+}
+
+const { filters, queryForApi, updateFilters, updateDefaults } = useL5(schema, {
+  defaults: {
+    category: [],
+    inStock: false
+  },
+  syncWithRoute: true,
+  urlUpdateStrategy: 'push'
+})
+
+updateFilters({ q: 'mac', category: ['laptops'] })
+```
+
+## Параметры `useL5`
+
+```ts
+interface Options<S> {
+  defaults?: Partial<InferFromL5Schema<S>>
+  syncWithRoute?: boolean
+  excludeFromSearch?: (keyof S)[]
+  apiIncludes?: string[]
+  excludeFromQueryBuilder?: (keyof S)[]
+  boolToNumber?: boolean
+  queryAliases?: Partial<Record<keyof S, string>>
+  transformInput?: (query: Partial<S>) => Partial<S>
+  transformOutput?: (filters: Filters<S>) => Record<keyof S & keyof BaseParams, unknown>
+  urlUpdateStrategy?: 'replace' | 'push'
+}
+```
+
+## Базовые параметры (BaseParams)
+
+Всегда доступны и участвуют в сборке запросов:
+
+- `page` (по умолчанию 1)
+- `limit` (по умолчанию 10)
+- `sortedBy` (по умолчанию `id`)
+- `orderBy` (по умолчанию `desc`)
+- `searchJoin` (по умолчанию `and`)
+- `searchFields` (по умолчанию `null`)
+- `search` (по умолчанию `null`)
+
+## Утилиты
+
+Модуль автоматически добавляет импорты:
+
+```ts
+import { buildQueryForApi, parseFiltersFromQuery } from '#imports'
+```
+
+- `buildQueryForApi(filters, options)` — сборка параметров для API
+- `parseFiltersFromQuery(schema, query, { defaults })` — парсинг query в фильтры
+
+## Возврат `useL5`
+
+```ts
+interface UseL5Return<S> {
+  filters: Ref<Filters<S>>
+  queryForApi: ShallowRef<Record<string, unknown>>
+  updateFilters: (newFilters: Partial<Filters<S>>, options?: { urlUpdateStrategy?: 'replace' | 'push' }) => void
+  updateDefaults: (newDefaults: Partial<InferFromL5Schema<S>>) => void
+  defaultsRef: Ref<Partial<InferFromL5Schema<S>>>
+}
+```
+
+## Лицензия
+
+MIT

package/dist/module.d.mts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export { BaseParams, Filters, InferFromL5Schema, InferL5, L5Node, Options, Primitive, SchemaDefinition } from '../dist/runtime/types/index.js';
+
+interface ModuleOptions {
+    syncWithRoute?: boolean;
+    urlUpdateStrategy?: 'replace' | 'push';
+    boolToNumber?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "use-l5",
+  "configKey": "useL5",
+  "compatibility": {
+    "nuxt": ">=3.16"
+  },
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,39 @@
+import { defineNuxtModule, createResolver, addImportsDir, addImports } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "use-l5",
+    configKey: "useL5",
+    compatibility: {
+      nuxt: ">=3.16"
+    }
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {},
+  setup(_options, _nuxt) {
+    const publicConfig = _nuxt.options.runtimeConfig.public ?? {};
+    const existing = publicConfig.useL5 ?? {};
+    const mergedOptions = {
+      ...existing,
+      ..._options
+    };
+    _nuxt.options.runtimeConfig.public = {
+      ...publicConfig,
+      useL5: mergedOptions
+    };
+    const resolver = createResolver(import.meta.url);
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addImports({
+      name: "buildQueryForApi",
+      as: "buildQueryForApi",
+      from: resolver.resolve("./runtime/utils/buildQueryForApi")
+    });
+    addImports({
+      name: "parseFiltersFromQuery",
+      as: "parseFiltersFromQuery",
+      from: resolver.resolve("./runtime/utils/parseFiltersFromQuery")
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/useL5.d.ts

@@ -0,0 +1,10 @@
+import type { Ref, ShallowRef } from 'vue';
+import type { Filters, InferFromL5Schema, Options, SchemaDefinition } from '../types/index.js';
+export interface UseL5Return<S extends SchemaDefinition> {
+    filters: Ref<Filters<S>>;
+    queryForApi: ShallowRef<Record<string, unknown>>;
+    updateFilters: (newFilters: Partial<Filters<S>>, _options?: Partial<Pick<Options<S>, 'urlUpdateStrategy'>>) => void;
+    updateDefaults: (newDefaults: Partial<InferFromL5Schema<S>>) => void;
+    defaultsRef: Ref<Partial<InferFromL5Schema<S>>>;
+}
+export declare function useL5<S extends SchemaDefinition>(scheme: S, options?: Options<S>): UseL5Return<S>;

package/dist/runtime/composables/useL5.js

@@ -0,0 +1,77 @@
+import {
+  shallowRef,
+  ref,
+  useRoute,
+  useRouter,
+  watch,
+  useRuntimeConfig
+} from "#imports";
+import { parseFiltersFromQuery } from "../utils/parseFiltersFromQuery.js";
+import { buildQueryForApi } from "../utils/buildQueryForApi.js";
+import { buildQueryForUrl } from "../utils/buildQueryForUrl.js";
+export function useL5(scheme, options = {}) {
+  const config = useRuntimeConfig();
+  const moduleOptions = config.public?.useL5 ?? {};
+  const route = useRoute();
+  const router = useRouter();
+  const mergedOptions = { ...moduleOptions, ...options };
+  const { syncWithRoute = false, urlUpdateStrategy = "push" } = mergedOptions;
+  const defaultsRef = ref(mergedOptions.defaults ?? {});
+  const query = syncWithRoute ? route.query : {};
+  const filters = ref(
+    parseFiltersFromQuery(scheme, query, {
+      defaults: defaultsRef.value
+    })
+  );
+  const queryForApi = shallowRef(
+    buildQueryForApi(filters.value, mergedOptions)
+  );
+  function updateFilters(newFilters, _options = {}) {
+    const {
+      urlUpdateStrategy: localUrlUpdateStrategy = urlUpdateStrategy
+    } = _options;
+    for (const key in newFilters) {
+      filters.value[key] = newFilters[key];
+    }
+    if (!syncWithRoute) {
+      queryForApi.value = buildQueryForApi(filters.value, mergedOptions);
+      return;
+    }
+    const query2 = buildQueryForUrl(filters.value, {
+      ...mergedOptions,
+      defaults: defaultsRef.value
+    });
+    const method = localUrlUpdateStrategy === "replace" ? router.replace : router.push;
+    method.call(router, { query: query2 });
+  }
+  function updateDefaults(newDefaults) {
+    defaultsRef.value = {
+      ...defaultsRef.value,
+      ...newDefaults
+    };
+  }
+  function startWatchingForRoute() {
+    watch(
+      () => route.query,
+      (newQuery) => {
+        filters.value = parseFiltersFromQuery(scheme, newQuery, {
+          defaults: defaultsRef.value
+        });
+        queryForApi.value = buildQueryForApi(
+          filters.value,
+          mergedOptions
+        );
+      }
+    );
+  }
+  if (syncWithRoute) {
+    startWatchingForRoute();
+  }
+  return {
+    filters,
+    queryForApi,
+    updateFilters,
+    updateDefaults,
+    defaultsRef
+  };
+}

package/dist/runtime/constant/baseParams.const.d.ts

@@ -0,0 +1,3 @@
+import type { BaseParams, L5Node } from '../types/index.js';
+export declare const BASE_PARAMS_DEFAULTS: BaseParams;
+export declare const BASE_PARAMS_DEFAULTS_TYPE_MAP: Record<keyof BaseParams, L5Node>;

package/dist/runtime/constant/baseParams.const.js

@@ -0,0 +1,18 @@
+export const BASE_PARAMS_DEFAULTS = {
+  page: 1,
+  limit: 10,
+  sortedBy: "id",
+  orderBy: "desc",
+  searchJoin: "and",
+  searchFields: null,
+  search: null
+};
+export const BASE_PARAMS_DEFAULTS_TYPE_MAP = {
+  page: Number,
+  limit: Number,
+  sortedBy: String,
+  orderBy: String,
+  searchJoin: String,
+  searchFields: String,
+  search: String
+};

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,33 @@
+export type Primitive = string | number | boolean | null | undefined;
+export type L5Node = StringConstructor | NumberConstructor | BooleanConstructor | [L5Node] | {
+    [k: string]: L5Node;
+};
+export type InferL5<T> = T extends StringConstructor ? string | null : T extends NumberConstructor ? number | null : T extends BooleanConstructor ? boolean : T extends [infer U] ? InferL5<U>[] : T extends Record<string, unknown> ? {
+    [K in keyof T]: InferL5<T[K]>;
+} : never;
+export type SchemaDefinition = Record<string, L5Node>;
+export type InferFromL5Schema<S extends SchemaDefinition> = {
+    [K in keyof S]: InferL5<S[K]>;
+};
+export type Filters<S extends SchemaDefinition> = InferL5<S> & BaseParams;
+export interface Options<S extends SchemaDefinition> {
+    defaults?: Partial<InferFromL5Schema<S>>;
+    syncWithRoute?: boolean;
+    excludeFromSearch?: (keyof S)[];
+    apiIncludes?: string[];
+    excludeFromQueryBuilder?: (keyof S)[];
+    boolToNumber?: boolean;
+    queryAliases?: Partial<Record<keyof S, string>>;
+    transformInput?: (query: Partial<S>) => Partial<S>;
+    transformOutput?: (filters: Filters<S>) => Record<keyof S & keyof BaseParams, unknown>;
+    urlUpdateStrategy?: 'replace' | 'push';
+}
+export interface BaseParams {
+    page: number;
+    limit: number;
+    sortedBy: string;
+    orderBy: string;
+    searchJoin: string;
+    searchFields: string | null;
+    search: string | null;
+}

package/dist/runtime/utils/buildQueryForApi.d.ts

@@ -0,0 +1,2 @@
+import type { Filters, SchemaDefinition, Options } from '../types/index.js';
+export declare function buildQueryForApi<S extends SchemaDefinition>(_filters: Filters<S>, options: Options<S>): Record<string, unknown>;

package/dist/runtime/utils/buildQueryForApi.js

@@ -0,0 +1,45 @@
+import { BASE_PARAMS_DEFAULTS } from "../constant/baseParams.const.js";
+import { pick } from "es-toolkit";
+const BASE_PARAMS_KEYS = Object.keys(BASE_PARAMS_DEFAULTS);
+export function buildQueryForApi(_filters, options) {
+  let filters = { ..._filters };
+  const result = pick(filters, BASE_PARAMS_KEYS);
+  const {
+    excludeFromSearch = [],
+    apiIncludes = [],
+    excludeFromQueryBuilder = [],
+    queryAliases,
+    transformOutput
+  } = options;
+  if (transformOutput) {
+    filters = transformOutput(_filters);
+  }
+  const allExcludeKeys = [...BASE_PARAMS_KEYS, ...excludeFromSearch];
+  if (options.boolToNumber) {
+    Object.entries(filters).forEach(([key, value]) => {
+      if (typeof value === "boolean") {
+        filters[key] = Number(value);
+      }
+    });
+  }
+  allExcludeKeys.forEach((key) => {
+    const alias = queryAliases?.[key] ?? key;
+    result[alias] = filters[key];
+  });
+  result.search = Object.entries(filters).filter(([key, value]) => {
+    if (BASE_PARAMS_KEYS.includes(key)) return false;
+    if (excludeFromSearch.includes(key)) return false;
+    if (excludeFromQueryBuilder.includes(key)) return false;
+    if (Array.isArray(value)) {
+      return value.length > 0;
+    }
+    return value !== null;
+  }).map(([key, value]) => {
+    const alias = queryAliases?.[key] ?? key;
+    return `${alias}:${Array.isArray(value) ? value.join(",") : value}`;
+  }).join(";");
+  if (apiIncludes.length) {
+    result.include = apiIncludes.join(",");
+  }
+  return result;
+}

package/dist/runtime/utils/buildQueryForUrl.d.ts

@@ -0,0 +1,3 @@
+import type { Filters, Options, SchemaDefinition } from '../types/index.js';
+import type { LocationQuery } from 'vue-router';
+export declare function buildQueryForUrl<S extends SchemaDefinition>(filters: Filters<S>, options: Options<S>): LocationQuery;

package/dist/runtime/utils/buildQueryForUrl.js

@@ -0,0 +1,17 @@
+import { BASE_PARAMS_DEFAULTS } from "../constant/baseParams.const.js";
+import { toMerged } from "es-toolkit/object";
+import { isEqualArray } from "./isEqualArray.js";
+export function buildQueryForUrl(filters, options) {
+  const defaults = toMerged(BASE_PARAMS_DEFAULTS, options.defaults ?? {});
+  return Object.entries(filters).filter(([key, value]) => {
+    if (value === null || value === void 0) return false;
+    const defaultValue = defaults?.[key];
+    if (Array.isArray(value) && Array.isArray(defaultValue)) {
+      return !isEqualArray(value, defaultValue);
+    }
+    return value !== defaultValue;
+  }).reduce((acc, [k, v]) => {
+    acc[k] = v;
+    return acc;
+  }, {});
+}

package/dist/runtime/utils/isEqualArray.d.ts

@@ -0,0 +1 @@
+export declare function isEqualArray(first: unknown[], second: unknown[]): boolean;

package/dist/runtime/utils/isEqualArray.js

@@ -0,0 +1,8 @@
+import { isEqual } from "es-toolkit/predicate";
+export function isEqualArray(first, second) {
+  if (first === second) return true;
+  if (first.length !== second.length) return false;
+  const normalizedFirst = [...first].sort();
+  const normalizedSecond = [...second].sort();
+  return isEqual(normalizedFirst, normalizedSecond);
+}

package/dist/runtime/utils/parseFiltersFromQuery.d.ts

@@ -0,0 +1,3 @@
+import type { Filters, SchemaDefinition, Options } from '../types/index.js';
+import type { LocationQuery } from 'vue-router';
+export declare function parseFiltersFromQuery<S extends SchemaDefinition>(scheme: S, query: LocationQuery, options: Required<Pick<Options<S>, 'defaults'>>): Filters<S>;

package/dist/runtime/utils/parseFiltersFromQuery.js

@@ -0,0 +1,19 @@
+import { parseValueFromQuery } from "./parseValueFromQuery.js";
+import { BASE_PARAMS_DEFAULTS, BASE_PARAMS_DEFAULTS_TYPE_MAP } from "../constant/baseParams.const.js";
+export function parseFiltersFromQuery(scheme, query, options) {
+  const result = {};
+  Object.keys(scheme).forEach((key) => {
+    if (!scheme[key]) return;
+    let value = query[key];
+    value ??= options.defaults[key];
+    result[key] = parseValueFromQuery(value, scheme[key]);
+  });
+  for (const key in BASE_PARAMS_DEFAULTS_TYPE_MAP) {
+    const typedKey = key;
+    let value = query[typedKey];
+    value ??= options.defaults[key];
+    value ??= BASE_PARAMS_DEFAULTS[typedKey];
+    result[key] = parseValueFromQuery(value, BASE_PARAMS_DEFAULTS_TYPE_MAP[typedKey]);
+  }
+  return result;
+}

package/dist/runtime/utils/parseValueFromQuery.d.ts

@@ -0,0 +1,3 @@
+import type { L5Node, Primitive } from '../types/index.js';
+import type { LocationQueryValue } from 'vue-router';
+export declare function parseValueFromQuery(value: LocationQueryValue | LocationQueryValue[] | Primitive | Primitive[], node: L5Node): Primitive | Primitive[];

package/dist/runtime/utils/parseValueFromQuery.js

@@ -0,0 +1,34 @@
+function asArray(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  return [value];
+}
+export function parseValueFromQuery(value, node) {
+  let isArray = false;
+  if (Array.isArray(node)) {
+    node = node[0];
+    isArray = true;
+  }
+  switch (node) {
+    case String:
+      if (isArray) {
+        return asArray(value).map((i) => String(i));
+      }
+      if (!value) return null;
+      return String(value);
+    case Number:
+      if (isArray) {
+        return asArray(value).map((i) => {
+          i = Number(i);
+          return Number.isNaN(i) ? null : i;
+        }).filter((i) => i);
+      }
+      if (!value) return null;
+      value = Number(value);
+      return Number.isNaN(value) ? null : value;
+    case Boolean:
+      if (!value) return false;
+      return ["1", "true"].includes(value.toString());
+    default:
+  }
+}

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { type BaseParams, type Filters, type InferFromL5Schema, type InferL5, type L5Node, type Options, type Primitive, type SchemaDefinition } from '../dist/runtime/types/index.js'
+
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "use-l5",
+    "version": "0.0.1",
+    "description": "Nuxt-модуль с типизированным useL5-композаблом для парсинга фильтров, синхронизации с query в роуте и сборки параметров для API/URL",
+    "author": {
+        "name": "Kirill Merkulov",
+        "url": "https://github.com/merkulovka"
+    },
+    "homepage": "https://github.com/merkulovka/use-l5#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/merkulovka/use-l5.git"
+    },
+    "license": "MIT",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/types.d.mts",
+            "import": "./dist/module.mjs"
+        },
+        "./runtime/*": {
+            "types": "./dist/runtime/*",
+            "import": "./dist/runtime/*"
+        }
+    },
+    "main": "./dist/module.mjs",
+    "typesVersions": {
+        "*": {
+            ".": [
+                "./dist/types.d.mts"
+            ],
+            "runtime/*": [
+                "./dist/runtime/*"
+            ]
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "prepack": "nuxt-module-build build",
+        "dev": "npm run dev:prepare && nuxi dev playground",
+        "dev:build": "nuxi build playground",
+        "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+        "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+        "lint": "eslint .",
+        "test": "vitest run",
+        "test:watch": "vitest watch",
+        "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+    },
+    "dependencies": {
+        "@nuxt/kit": "^4.2.1",
+        "es-toolkit": "^1.42.0"
+    },
+    "devDependencies": {
+        "@nuxt/devtools": "^3.1.0",
+        "@nuxt/eslint-config": "^1.10.0",
+        "@nuxt/module-builder": "^1.0.2",
+        "@nuxt/schema": "^4.2.1",
+        "@nuxt/test-utils": "^3.20.1",
+        "@types/node": "latest",
+        "changelogen": "^0.6.2",
+        "eslint": "^9.39.1",
+        "nuxt": "^4.2.1",
+        "typescript": "~5.9.3",
+        "vitest": "^4.0.10",
+        "vue-tsc": "^3.1.4"
+    },
+    "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
+}