@plumile/filter-query 0.1.28 → 0.1.30

package/src/__tests__/parse.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { defineSchema, numberField, stringField } from '../schema.js';
+import { parse } from '../parse.js';
+
+const schema = defineSchema({
+  title: stringField(),
+  price: numberField(),
+});
+
+describe('parse helpers', () => {
+  it('parses implicit equality and explicit operators into the same field object', () => {
+    const result = parse('?title=foo&title.contains=bar', schema);
+    expect(result.filters.title).toEqual({
+      eq: 'foo',
+      contains: 'bar',
+    });
+    expect(result.diagnostics).toEqual([]);
+  });
+
+  it('handles between operator arity and numeric validation', () => {
+    const ok = parse('price.between=1,3', schema);
+    expect(ok.filters.price?.between).toEqual([1, 3]);
+    expect(ok.diagnostics).toEqual([]);
+
+    const wrongArity = parse('price.between=1', schema);
+    expect(wrongArity.filters.price).toBeUndefined();
+    expect(wrongArity.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'InvalidArity',
+        field: 'price',
+        operator: 'between',
+      }),
+    );
+
+    const invalidValue = parse('price.between=1,not-a-number', schema);
+    expect(invalidValue.filters.price).toBeUndefined();
+    expect(invalidValue.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'InvalidValue',
+        field: 'price',
+        operator: 'between',
+      }),
+    );
+  });
+
+  it('records duplicate between declarations as diagnostics', () => {
+    const result = parse('price.between=1,3&price.between=2,4', schema);
+    expect(result.filters.price?.between).toEqual([1, 3]);
+    expect(result.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'DuplicateBetween',
+        field: 'price',
+      }),
+    );
+  });
+
+  it('aggregates list operators and appends across segments', () => {
+    const list = parse('title.in=foo,bar%20baz&title.in=qux', schema);
+    expect(list.filters.title?.in).toEqual(['foo', 'bar baz', 'qux']);
+    expect(list.diagnostics).toEqual([]);
+
+    const numericList = parse('price.in=1,NaN,3', schema);
+    expect(numericList.filters.price?.in).toEqual([1, 3]);
+    expect(numericList.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'InvalidValue',
+        field: 'price',
+        operator: 'in',
+      }),
+    );
+  });
+
+  it('decodes values and reports decode failures', () => {
+    const decoded = parse('title.contains=hello%20world', schema);
+    expect(decoded.filters.title?.contains).toBe('hello world');
+    expect(decoded.diagnostics).toEqual([]);
+
+    const failure = parse('title.eq=%', schema);
+    expect(failure.filters.title).toBeUndefined();
+    expect(failure.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'DecodeError',
+        field: 'title',
+        operator: 'eq',
+      }),
+    );
+  });
+
+  it('validates scalar numeric operators and surfaces invalid values', () => {
+    const ok = parse('price.eq=42', schema);
+    expect(ok.filters.price?.eq).toBe(42);
+
+    const bad = parse('price.eq=', schema);
+    expect(bad.filters.price).toBeUndefined();
+    expect(bad.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'InvalidValue',
+        field: 'price',
+        operator: 'eq',
+      }),
+    );
+  });
+
+  it('reports unknown fields and operators', () => {
+    const field = parse('unknown.eq=value', schema);
+    expect(field.filters.unknown as unknown).toBeUndefined();
+    expect(field.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'UnknownField',
+        field: 'unknown',
+      }),
+    );
+
+    const operator = parse('title.between=foo,bar', schema);
+    expect(operator.filters.title).toBeUndefined();
+    expect(operator.diagnostics).toContainEqual(
+      expect.objectContaining({
+        kind: 'UnknownOperator',
+        field: 'title',
+        operator: 'between',
+      }),
+    );
+  });
+
+  it('returns empty result for blank input', () => {
+    expect(parse('', schema)).toEqual({ filters: {}, diagnostics: [] });
+    expect(parse('   ', schema)).toEqual({ filters: {}, diagnostics: [] });
+    expect(parse('?', schema)).toEqual({ filters: {}, diagnostics: [] });
+  });
+});

package/src/__tests__/schema.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { numberField, stringField, defineSchema } from '../schema.js';
+
+describe('schema helpers', () => {
+  it('numberField parses finite numbers and rejects invalid input', () => {
+    const descriptor = numberField();
+    expect(descriptor.kind).toBe('number');
+    expect(descriptor.operators).toContain('between');
+    expect(descriptor.parse('42')).toBe(42);
+    expect(descriptor.parse('')).toBeUndefined();
+    expect(descriptor.parse('NaN')).toBeUndefined();
+    expect(descriptor.serialize(13)).toBe('13');
+  });
+
+  it('stringField returns raw strings and serializes values', () => {
+    const descriptor = stringField(['eq', 'contains']);
+    expect(descriptor.kind).toBe('string');
+    expect(descriptor.operators).toEqual(['eq', 'contains']);
+    expect(descriptor.parse('hello')).toBe('hello');
+    expect(descriptor.serialize(100)).toBe('100');
+  });
+
+  it('defineSchema freezes the returned schema copy', () => {
+    const source = { title: stringField() };
+    const schema = defineSchema(source);
+    expect(schema).not.toBe(source);
+    expect(Object.isFrozen(schema)).toBe(true);
+    expect(schema.title).toBeDefined();
+  });
+});

package/src/__tests__/stringify.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { defineSchema, numberField, stringField } from '../schema.js';
+import { parse } from '../parse.js';
+import { stringify } from '../stringify.js';
+import type { InferFilters } from '../types.js';
+
+const schema = defineSchema({
+  title: stringField(['eq', 'contains', 'in']),
+  price: numberField(['eq', 'between', 'in', 'nin']),
+});
+
+describe('stringify helpers', () => {
+  it('omits dot for implicit equality and uses dotted keys for other operators', () => {
+    const { filters } = parse('title=hello&title.contains=world', schema);
+    const output = stringify(filters, schema);
+    const segments = output.split('&');
+    expect(segments).toContain('title=hello');
+    expect(segments).toContain('title.contains=world');
+  });
+
+  it('serializes operators in schema order including between and list variants', () => {
+    const { filters } = parse(
+      'title=hello&title.contains=world&price=1&price.between=1,4&price.in=2,3&price.nin=5,6',
+      schema,
+    );
+    const output = stringify(filters, schema);
+    expect(output.split('&')).toEqual([
+      'title=hello',
+      'title.contains=world',
+      'price=1',
+      'price.between=1,4',
+      'price.in=2,3',
+      'price.nin=5,6',
+    ]);
+  });
+
+  it('stringifies non primitive scalars before encoding', () => {
+    const customSchema = defineSchema({
+      meta: stringField(['eq']),
+    });
+    type CustomFilters = InferFilters<typeof customSchema>;
+    const filters: CustomFilters = {
+      meta: {
+        eq: { nested: true } as unknown,
+      },
+    };
+    const output = stringify(filters, customSchema);
+    expect(output).toBe(
+      `meta=${encodeURIComponent(JSON.stringify({ nested: true }))}`,
+    );
+  });
+
+  it('skips operators with undefined or empty values', () => {
+    type Filters = InferFilters<typeof schema>;
+    const filters: Filters = {
+      title: {
+        contains: 'value',
+      },
+      price: {} as Filters['price'],
+    };
+    const output = stringify(filters, schema);
+    expect(output).toBe('title.contains=value');
+  });
+});

package/src/errors.ts

@@ -1,3 +1,6 @@
+/**
+ * Union of all diagnostic variants that can be produced while parsing a filter query string.
+ */
 export type Diagnostic =
   | UnknownFieldDiagnostic
   | UnknownOperatorDiagnostic
@@ -6,6 +9,10 @@ export type Diagnostic =
   | DuplicateBetweenDiagnostic
   | DecodeErrorDiagnostic;
 
+/**
+ * Common diagnostic shape.
+ * Consumers should refine via the `kind` discriminant before reading additional fields.
+ */
 export interface BaseDiagnostic {
   readonly kind: string;
   readonly field?: string;
@@ -13,31 +20,53 @@ export interface BaseDiagnostic {
   readonly detail?: string;
 }
 
+/**
+ * Raised when the query references a field that is not present in the schema definition.
+ */
 export interface UnknownFieldDiagnostic extends BaseDiagnostic {
   kind: 'UnknownField';
   field: string;
 }
+/**
+ * Raised when a field is known but an operator that is not whitelisted on the schema
+ * is encountered.
+ */
 export interface UnknownOperatorDiagnostic extends BaseDiagnostic {
   kind: 'UnknownOperator';
   field: string;
   operator: string;
 }
+/**
+ * Signals that a value could not be parsed according to the field descriptor
+ * (e.g. malformed number).
+ */
 export interface InvalidValueDiagnostic extends BaseDiagnostic {
   kind: 'InvalidValue';
   field: string;
   operator: string;
   detail?: string;
 }
+/**
+ * Emitted when an operator receives an unexpected number of values
+ * (e.g. `between` without exactly two items).
+ */
 export interface InvalidArityDiagnostic extends BaseDiagnostic {
   kind: 'InvalidArity';
   field: string;
   operator: string;
   detail: string; // expected arity info
 }
+/**
+ * Indicates that multiple `between` declarations were encountered for the same field;
+ * only the first is kept.
+ */
 export interface DuplicateBetweenDiagnostic extends BaseDiagnostic {
   kind: 'DuplicateBetween';
   field: string;
 }
+/**
+ * Raised when a value cannot be decoded from the URL query string (invalid percent-encoding).
+ */
 export interface DecodeErrorDiagnostic extends BaseDiagnostic {
   kind: 'DecodeError';
   field: string;

package/src/mutate.ts

@@ -1,7 +1,7 @@
 import type { InferFilters, Schema } from './types.js';
 
 /**
- * Shallow object equality (own enumerable string keys only).
+ * Checks shallow equality between two plain objects (own enumerable string keys only).
  */
 function shallowEqual(a: unknown, b: unknown): boolean {
   if (a === b) {
@@ -31,7 +31,14 @@ function shallowEqual(a: unknown, b: unknown): boolean {
 }
 
 /**
- * Set or unset a specific operator value for a field.
+ * Sets or unsets a specific operator value on a field while preserving reference
+ * equality when nothing changes.
+ *
+ * @param filters - Current filters object that will be treated as immutable input.
+ * @param _schema - Schema reference (reserved for future validation hooks).
+ * @param field - Field key to update.
+ * @param operator - Operator name to set or remove.
+ * @param value - New operator value; pass `undefined` to remove it.
  */
 export function setFilter<
   S extends Schema,
@@ -70,7 +77,11 @@ export function setFilter<
 }
 
 /**
- * Remove either an entire field or a specific operator inside a field.
+ * Removes either an entire field or a specific operator from the filters object.
+ *
+ * @param filters - Current filters object (treated immutably).
+ * @param field - Field name to alter.
+ * @param operator - Optional operator to remove; omit to drop the whole field.
  */
 export function removeFilter<S extends Schema, F extends keyof S>(
   filters: Readonly<InferFilters<S>>,
@@ -97,7 +108,11 @@ export function removeFilter<S extends Schema, F extends keyof S>(
 }
 
 /**
- * Merge two filters objects preserving reference identity for unchanged fields.
+ * Merges a patch of filters into an existing filters object while preserving reference
+ * identity for unchanged fields.
+ *
+ * @param base - Original filters.
+ * @param patch - Filters to overlay.
  */
 export function mergeFilters<S extends Schema>(
   base: Readonly<InferFilters<S>>,
@@ -124,7 +139,11 @@ export function mergeFilters<S extends Schema>(
   return base as InferFilters<S>;
 }
 
-/** Determine if the filters object is empty (no fields). */
+/**
+ * Determines if the filters object is empty (no fields present).
+ *
+ * @param filters - Filters to inspect.
+ */
 export function isEmpty<S extends Schema>(
   filters: Readonly<InferFilters<S>>,
 ): boolean {

package/src/parse.ts

@@ -168,7 +168,14 @@ function handleScalar<S extends Schema>(
   scalarTarget[operator] = scalar;
 }
 
-/** Parse a raw search string (leading ? optional) according to the provided schema. */
+/**
+ * Parses a raw search string (leading `?` optional) according to the provided schema
+ * and returns the filters plus diagnostics.
+ *
+ * @param rawSearch - Query string to parse (with or without the leading question mark).
+ * @param schema - Schema describing allowed fields and operators.
+ * @returns Parsed filters alongside non-blocking diagnostics.
+ */
 export function parse<S extends Schema>(
   rawSearch: string,
   schema: S,

package/src/stringify.ts

@@ -1,12 +1,20 @@
 import type { InferFilters, Schema, Operator } from './types.js';
 
-/** Build encoded key portion for non-eq operators */
+/**
+ * Builds the encoded key portion for a field/operator pair (implicit `eq` has no dot suffix).
+ */
 function encodeKey(field: string, op: Operator): string {
   if (op === 'eq') return field; // implicit equality form
   return `${field}.${op}`;
 }
 
-/** Serialize filters object into a query string. */
+/**
+ * Serializes a filters object into a canonical query string respecting the schema operator ordering.
+ *
+ * @param filters - Parsed filters to encode.
+ * @param schema - Schema used to determine operator ordering and formatting.
+ * @returns Query string without leading question mark.
+ */
 export function stringify<S extends Schema>(
   filters: InferFilters<S>,
   schema: S,

package/src/types.ts

@@ -1,5 +1,8 @@
 import type { Diagnostic } from './errors.js';
 
+/**
+ * Operators that take a single scalar value (numbers or strings) in the filter schema.
+ */
 export type ScalarOperator =
   | 'gt'
   | 'gte'
@@ -10,12 +13,19 @@ export type ScalarOperator =
   | 'contains'
   | 'sw'
   | 'ew';
+/** Operator representing a range of two values. */
 export type BetweenOperator = 'between';
+/** Operators whose values are lists. */
 export type ListOperator = 'in' | 'nin';
+/** All supported operator kinds. */
 export type Operator = ScalarOperator | BetweenOperator | ListOperator;
 
+/** Primitive field kinds supported by the schema. */
 export type PrimitiveKind = 'number' | 'string';
 
+/**
+ * Base descriptor shared by number and string fields.
+ */
 export interface FieldDescriptorBase<TKind extends PrimitiveKind> {
   readonly kind: TKind;
   readonly operators: readonly Operator[];
@@ -23,17 +33,21 @@ export interface FieldDescriptorBase<TKind extends PrimitiveKind> {
   readonly serialize?: (value: unknown) => string;
 }
 
+/** Descriptor for numeric fields. Provides numeric parsing/serialisation hooks. */
 export type NumberFieldDescriptor = FieldDescriptorBase<'number'> & {
   readonly parse?: (raw: string) => number | undefined;
   readonly serialize?: (value: number) => string;
 };
+/** Descriptor for string fields. Provides string parsing/serialisation hooks. */
 export type StringFieldDescriptor = FieldDescriptorBase<'string'> & {
   readonly parse?: (raw: string) => string | undefined;
   readonly serialize?: (value: string) => string;
 };
 
+/** Descriptor accepted by the schema (number or string). */
 export type FieldDescriptor = NumberFieldDescriptor | StringFieldDescriptor;
 
+/** Immutable mapping between field keys and their descriptors. */
 export type Schema = Readonly<Record<string, FieldDescriptor>>;
 
 // Infer operator mapping for a single field descriptor
@@ -78,10 +92,12 @@ export type InferField<D extends FieldDescriptor> = Partial<
   ScalarMap<D> & BetweenMap<D> & ListMap<D>
 >;
 
+/** Filters map inferred from a schema definition. */
 export type InferFilters<S extends Schema> = {
   [K in keyof S]?: InferField<S[K]>;
 };
 
+/** Result returned by the `parse` function: parsed filters plus diagnostics. */
 export interface ParseResult<S extends Schema> {
   readonly filters: InferFilters<S>;
   readonly diagnostics: Diagnostic[];