@plumile/filter-query 0.1.17

package/src/mutate.ts

@@ -0,0 +1,132 @@
+import type { InferFilters, Schema } from './types.js';
+
+/**
+ * Shallow object equality (own enumerable string keys only).
+ */
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (
+    typeof a !== 'object' ||
+    a === null ||
+    typeof b !== 'object' ||
+    b === null
+  ) {
+    return false;
+  }
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  for (const k of aKeys) {
+    if (aObj[k] !== bObj[k]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Set or unset a specific operator value for a field.
+ */
+export function setFilter<
+  S extends Schema,
+  F extends keyof S,
+  O extends keyof NonNullable<InferFilters<S>[F]>,
+>(
+  filters: Readonly<InferFilters<S>>,
+  _schema: S, // reserved for future validation hooks
+  field: F,
+  operator: O,
+  value: NonNullable<InferFilters<S>[F]>[O] | undefined,
+): InferFilters<S> {
+  const currentField = filters[field];
+  if (value === undefined) {
+    if (currentField === undefined) {
+      return filters as InferFilters<S>;
+    }
+    const { [operator]: _removed, ...rest } = currentField as Record<
+      string,
+      unknown
+    >;
+    if (Object.keys(rest).length === 0) {
+      const { [field]: _f, ...clone } = filters as Record<string, unknown>;
+      return clone as InferFilters<S>;
+    }
+    return { ...filters, [field]: rest } as InferFilters<S>;
+  }
+  const newField = {
+    ...(currentField as Record<string, unknown> | undefined),
+    [operator]: value,
+  };
+  if (currentField !== undefined && shallowEqual(currentField, newField)) {
+    return filters as InferFilters<S>;
+  }
+  return { ...filters, [field]: newField } as InferFilters<S>;
+}
+
+/**
+ * Remove either an entire field or a specific operator inside a field.
+ */
+export function removeFilter<S extends Schema, F extends keyof S>(
+  filters: Readonly<InferFilters<S>>,
+  field: F,
+  operator?: keyof NonNullable<InferFilters<S>[F]>,
+): InferFilters<S> {
+  const currentField = filters[field];
+  if (currentField === undefined) {
+    return filters as InferFilters<S>;
+  }
+  if (operator === undefined) {
+    const { [field]: _removed, ...clone } = filters as Record<string, unknown>;
+    return clone as InferFilters<S>;
+  }
+  const { [operator]: _opRemoved, ...rest } = currentField as Record<
+    string,
+    unknown
+  >;
+  if (Object.keys(rest).length === 0) {
+    const { [field]: _f, ...clone } = filters as Record<string, unknown>;
+    return clone as InferFilters<S>;
+  }
+  return { ...filters, [field]: rest } as InferFilters<S>;
+}
+
+/**
+ * Merge two filters objects preserving reference identity for unchanged fields.
+ */
+export function mergeFilters<S extends Schema>(
+  base: Readonly<InferFilters<S>>,
+  patch: Readonly<InferFilters<S>>,
+): InferFilters<S> {
+  let changed = false;
+  const result: Partial<InferFilters<S>> = { ...base };
+  for (const key of Object.keys(patch) as (keyof S)[]) {
+    const existing = base[key];
+    const incoming = patch[key];
+    if (incoming === undefined) {
+      // skip undefined incoming
+    } else if (existing === undefined) {
+      result[key] = incoming as InferFilters<S>[typeof key];
+      changed = true;
+    } else if (!shallowEqual(existing, incoming)) {
+      result[key] = incoming as InferFilters<S>[typeof key];
+      changed = true;
+    }
+  }
+  if (changed) {
+    return result as InferFilters<S>;
+  }
+  return base as InferFilters<S>;
+}
+
+/** Determine if the filters object is empty (no fields). */
+export function isEmpty<S extends Schema>(
+  filters: Readonly<InferFilters<S>>,
+): boolean {
+  return Object.keys(filters).length === 0;
+}

package/src/parse.ts

@@ -0,0 +1,221 @@
+import type {
+  Schema,
+  Operator,
+  ListOperator,
+  BetweenOperator,
+  InferFilters,
+  FieldDescriptor,
+  ParseResult,
+} from './types.js';
+import type { Diagnostic } from './errors.js';
+
+const BETWEEN: BetweenOperator = 'between';
+const LIST_OPS: readonly ListOperator[] = ['in', 'nin'];
+
+interface InternalAccumulator<S extends Schema> {
+  filters: InferFilters<S>;
+  diagnostics: Diagnostic[];
+}
+
+/** Shallow clone plus ensure field object helper (immutable update). */
+function ensureFieldObject<S extends Schema>(
+  filters: InferFilters<S>,
+  field: string,
+): { container: InferFilters<S>; target: Record<string, unknown> } {
+  const existing = filters[field as keyof S] as
+    | Record<string, unknown>
+    | undefined;
+  if (existing !== undefined) {
+    return { container: filters, target: existing };
+  }
+  const clone: InferFilters<S> = { ...filters };
+  const created: Record<string, unknown> = {};
+  (clone as Record<string, unknown>)[field] = created;
+  return { container: clone, target: created };
+}
+
+/** Decode component, recording a diagnostic on failure. */
+function decodeValue(
+  value: string,
+  field: string,
+  operator: string,
+  diagnostics: Diagnostic[],
+): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    diagnostics.push({
+      kind: 'DecodeError',
+      field,
+      operator,
+      detail: 'Failed to decode',
+    });
+    return undefined;
+  }
+}
+
+/** Parse a single raw value according to field kind. */
+function parseSingleValue(
+  descriptor: FieldDescriptor,
+  raw: string,
+): string | number | undefined {
+  if (descriptor.kind === 'number') {
+    if (raw === '') {
+      // Treat empty string as invalid for numeric fields (reject instead of coercing to 0)
+      return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+      return undefined;
+    }
+    return n;
+  }
+  return raw;
+}
+
+/** Handle a between operator value. */
+function handleBetween<S extends Schema>(
+  descriptor: FieldDescriptor,
+  decoded: string,
+  field: string,
+  operator: string,
+  acc: InternalAccumulator<S>,
+): void {
+  const parts: string[] = decoded.split(',');
+  if (parts.length !== 2) {
+    acc.diagnostics.push({
+      kind: 'InvalidArity',
+      field,
+      operator,
+      detail: 'Expected exactly 2 values',
+    });
+    return;
+  }
+  const [aRaw, bRaw] = parts as [string, string];
+  const a = parseSingleValue(descriptor, aRaw);
+  const b = parseSingleValue(descriptor, bRaw);
+  if (a === undefined || b === undefined) {
+    acc.diagnostics.push({
+      kind: 'InvalidValue',
+      field,
+      operator,
+      detail: 'One of the between values invalid',
+    });
+    return;
+  }
+  const ensured = ensureFieldObject(acc.filters, field);
+  acc.filters = ensured.container;
+  if (Object.prototype.hasOwnProperty.call(ensured.target, 'between')) {
+    acc.diagnostics.push({ kind: 'DuplicateBetween', field });
+    return;
+  }
+  ensured.target.between = [a, b] as unknown;
+}
+
+/** Handle list operators (in, nin). */
+function handleList<S extends Schema>(
+  descriptor: FieldDescriptor,
+  decoded: string,
+  field: string,
+  operator: string,
+  acc: InternalAccumulator<S>,
+): void {
+  const listRaw = decoded.split(',');
+  const parsedList: (string | number)[] = [];
+  for (const item of listRaw) {
+    const parsed = parseSingleValue(descriptor, item);
+    if (parsed === undefined) {
+      acc.diagnostics.push({
+        kind: 'InvalidValue',
+        field,
+        operator,
+        detail: 'List item invalid',
+      });
+    } else {
+      parsedList.push(parsed);
+    }
+  }
+  if (parsedList.length === 0) {
+    return;
+  }
+  const ensured = ensureFieldObject(acc.filters, field);
+  acc.filters = ensured.container;
+  const targetObj: Record<string, unknown> = ensured.target;
+  const existing = targetObj[operator];
+  if (Array.isArray(existing)) {
+    targetObj[operator] = [...existing, ...parsedList];
+  } else {
+    targetObj[operator] = parsedList;
+  }
+}
+
+/** Handle scalar operator values. */
+function handleScalar<S extends Schema>(
+  descriptor: FieldDescriptor,
+  decoded: string,
+  field: string,
+  operator: string,
+  acc: InternalAccumulator<S>,
+): void {
+  const scalar = parseSingleValue(descriptor, decoded);
+  if (scalar === undefined) {
+    acc.diagnostics.push({ kind: 'InvalidValue', field, operator });
+    return;
+  }
+  const ensured = ensureFieldObject(acc.filters, field);
+  acc.filters = ensured.container;
+  const scalarTarget: Record<string, unknown> = ensured.target;
+  scalarTarget[operator] = scalar;
+}
+
+/** Parse a raw search string (leading ? optional) according to the provided schema. */
+export function parse<S extends Schema>(
+  rawSearch: string,
+  schema: S,
+): ParseResult<S> {
+  const acc: InternalAccumulator<S> = { filters: {}, diagnostics: [] };
+  let search = rawSearch;
+  if (search.startsWith('?')) {
+    search = search.slice(1);
+  }
+  if (search.trim() === '') {
+    return acc;
+  }
+  const segments = search.split('&');
+  for (const seg of segments) {
+    const eqIdx = seg.indexOf('=');
+    const validBasic = seg !== '' && eqIdx !== -1;
+    if (validBasic) {
+      const rawKey = seg.slice(0, eqIdx);
+      const rawVal = seg.slice(eqIdx + 1);
+      const lastDot = rawKey.lastIndexOf('.');
+      const keyShapeOk = !(lastDot <= 0 || lastDot === rawKey.length - 1);
+      if (keyShapeOk) {
+        const field = rawKey.slice(0, lastDot);
+        const operator = rawKey.slice(lastDot + 1) as Operator;
+        const descriptor = schema[field];
+        const descOk = descriptor?.operators.includes(operator) === true;
+        if (!descOk) {
+          if (descriptor === undefined) {
+            acc.diagnostics.push({ kind: 'UnknownField', field });
+          } else {
+            acc.diagnostics.push({ kind: 'UnknownOperator', field, operator });
+          }
+        } else {
+          const decoded = decodeValue(rawVal, field, operator, acc.diagnostics);
+          if (decoded !== undefined) {
+            const isList = (LIST_OPS as readonly string[]).includes(operator);
+            if (operator === BETWEEN) {
+              handleBetween(descriptor, decoded, field, operator, acc);
+            } else if (isList) {
+              handleList(descriptor, decoded, field, operator, acc);
+            } else {
+              handleScalar(descriptor, decoded, field, operator, acc);
+            }
+          }
+        }
+      }
+    }
+  }
+  return acc;
+}

package/src/schema.ts

@@ -0,0 +1,81 @@
+import type {
+  FieldDescriptor,
+  NumberFieldDescriptor,
+  Schema,
+  StringFieldDescriptor,
+  Operator,
+} from './types.js';
+
+const DEFAULT_NUMBER_OPERATORS: readonly Operator[] = [
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'eq',
+  'neq',
+  'between',
+  'in',
+  'nin',
+];
+const DEFAULT_STRING_OPERATORS: readonly Operator[] = [
+  'contains',
+  'sw',
+  'ew',
+  'eq',
+  'neq',
+  'in',
+  'nin',
+];
+
+/**
+ * Create a numeric field descriptor with a given operator whitelist.
+ */
+export function numberField(
+  ops: readonly Operator[] = DEFAULT_NUMBER_OPERATORS,
+): NumberFieldDescriptor {
+  return {
+    kind: 'number',
+    operators: ops,
+    parse(raw: string): number | undefined {
+      if (raw === '') {
+        return undefined;
+      }
+      const n = Number(raw);
+      if (Number.isFinite(n)) {
+        return n;
+      }
+      return undefined;
+    },
+    // Accept unknown to satisfy base interface intersection; caller ensures type correctness
+    serialize(value: unknown): string {
+      return String(value as number);
+    },
+  } as NumberFieldDescriptor;
+}
+
+/**
+ * Create a string field descriptor with a given operator whitelist.
+ */
+export function stringField(
+  ops: readonly Operator[] = DEFAULT_STRING_OPERATORS,
+): StringFieldDescriptor {
+  return {
+    kind: 'string',
+    operators: ops,
+    parse(raw: string): string | undefined {
+      return raw;
+    },
+    serialize(value: unknown): string {
+      return String(value as string);
+    },
+  } as StringFieldDescriptor;
+}
+
+/**
+ * Freeze and return the schema (immutability guard for consumers).
+ */
+export function defineSchema<S extends Record<string, FieldDescriptor>>(
+  schema: S,
+): Schema & S {
+  return Object.freeze({ ...schema });
+}

package/src/stringify.ts

@@ -0,0 +1,60 @@
+import type { InferFilters, Schema, Operator } from './types.js';
+
+/** Build encoded key portion field.op */
+function encodeKey(field: string, op: Operator): string {
+  return `${field}.${op}`;
+}
+
+/** Serialize filters object into a query string. */
+export function stringify<S extends Schema>(
+  filters: InferFilters<S>,
+  schema: S,
+): string {
+  const parts: string[] = [];
+  for (const field of Object.keys(schema)) {
+    const value = filters[field as keyof S];
+    const descriptor = schema[field];
+    if (value === undefined || descriptor === undefined) {
+      // skip absent
+    } else {
+      for (const op of descriptor.operators) {
+        if (op === 'between') {
+          const tuple = (value as Record<string, unknown>).between as
+            | unknown[]
+            | undefined;
+          if (Array.isArray(tuple) && tuple.length === 2) {
+            const first = encodeURIComponent(String(tuple[0]));
+            const second = encodeURIComponent(String(tuple[1]));
+            parts.push(`${encodeKey(field, op)}=${first},${second}`);
+          }
+        } else if (op === 'in' || op === 'nin') {
+          const list = (value as Record<string, unknown>)[op] as
+            | unknown[]
+            | undefined;
+          if (Array.isArray(list) && list.length > 0) {
+            const encodedItems = list
+              .map((v) => {
+                return encodeURIComponent(String(v));
+              })
+              .join(',');
+            parts.push(`${encodeKey(field, op)}=${encodedItems}`);
+          }
+        } else {
+          const scalar = (value as Record<string, unknown>)[op];
+          if (scalar !== undefined) {
+            let printable: unknown;
+            if (typeof scalar === 'string' || typeof scalar === 'number') {
+              printable = scalar;
+            } else {
+              printable = JSON.stringify(scalar);
+            }
+            parts.push(
+              `${encodeKey(field, op)}=${encodeURIComponent(String(printable))}`,
+            );
+          }
+        }
+      }
+    }
+  }
+  return parts.join('&');
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { Diagnostic } from './errors.js';
+
+export type ScalarOperator =
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'eq'
+  | 'neq'
+  | 'contains'
+  | 'sw'
+  | 'ew';
+export type BetweenOperator = 'between';
+export type ListOperator = 'in' | 'nin';
+export type Operator = ScalarOperator | BetweenOperator | ListOperator;
+
+export type PrimitiveKind = 'number' | 'string';
+
+export interface FieldDescriptorBase<TKind extends PrimitiveKind> {
+  readonly kind: TKind;
+  readonly operators: readonly Operator[];
+  readonly parse?: (raw: string) => unknown;
+  readonly serialize?: (value: unknown) => string;
+}
+
+export type NumberFieldDescriptor = FieldDescriptorBase<'number'> & {
+  readonly parse?: (raw: string) => number | undefined;
+  readonly serialize?: (value: number) => string;
+};
+export type StringFieldDescriptor = FieldDescriptorBase<'string'> & {
+  readonly parse?: (raw: string) => string | undefined;
+  readonly serialize?: (value: string) => string;
+};
+
+export type FieldDescriptor = NumberFieldDescriptor | StringFieldDescriptor;
+
+export type Schema = Readonly<Record<string, FieldDescriptor>>;
+
+// Infer operator mapping for a single field descriptor
+type OperatorKeys<D extends FieldDescriptor> = Extract<
+  D['operators'][number],
+  ScalarOperator
+>;
+type ScalarMap<D extends FieldDescriptor> =
+  D extends FieldDescriptorBase<'number'>
+    ? Record<OperatorKeys<D>, number | undefined>
+    : Record<OperatorKeys<D>, string | undefined>;
+
+type BetweenMap<D extends FieldDescriptor> =
+  'between' extends D['operators'][number]
+    ? {
+        between?: D extends FieldDescriptorBase<'number'>
+          ? readonly [number, number]
+          : readonly [string, string];
+      }
+    : Record<never, never>;
+
+type ListOps<D extends FieldDescriptor> = Extract<
+  D['operators'][number],
+  ListOperator
+>;
+type ListMap<D extends FieldDescriptor> = ('in' extends ListOps<D>
+  ? {
+      in?: D extends FieldDescriptorBase<'number'>
+        ? readonly number[]
+        : readonly string[];
+    }
+  : Record<never, never>) &
+  ('nin' extends ListOps<D>
+    ? {
+        nin?: D extends FieldDescriptorBase<'number'>
+          ? readonly number[]
+          : readonly string[];
+      }
+    : Record<never, never>);
+
+export type InferField<D extends FieldDescriptor> = Partial<
+  ScalarMap<D> & BetweenMap<D> & ListMap<D>
+>;
+
+export type InferFilters<S extends Schema> = {
+  [K in keyof S]?: InferField<S[K]>;
+};
+
+export interface ParseResult<S extends Schema> {
+  readonly filters: InferFilters<S>;
+  readonly diagnostics: Diagnostic[];
+}

package/tools/build-package.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run build:package:esm
+npm run build:package:types

package/tools/test-build-package.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run build:package:types

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib", "**/__tests__/**"]
+}

package/tsconfig.esm.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "outDir": "./lib/esm"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "./src"
+  },
+  "exclude": ["lib", "vitest.config.ts", "src/__tests__/**"]
+}

package/tsconfig.types.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "./lib/types",
+    "declarationMap": true,
+    "emitDeclarationOnly": true
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+  },
+});