@owlmeans/resource 0.1.18-rc.9 → 0.1.18

package/src/utils/consts.local.ts

@@ -0,0 +1 @@
+export const COMPARISON = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte'])

package/src/utils/name.ts

@@ -1,5 +1,5 @@
-import type {Context, Config, ResourceDbService, DbConfig} from '../types.js'
+import type { Context, Config, ResourceDbService, DbConfig } from '../types.js'
 
 export const dbName = <C extends Config, T extends Context<C> = Context<C>>(
   _context: T, service: ResourceDbService<any, any>, config: DbConfig
-) => config.schema ?? config.alias ?? service.alias
+): string => config.schema ?? config.alias ?? service.alias

package/src/utils/query/types.ts

@@ -0,0 +1,37 @@
+import type { Criteria, ListOptions, ListResult, ResourceRecord, Sort } from '../../types.js'
+
+/**
+ * In-memory evaluation of `Criteria<any>` — the engine every store without a query language of its
+ * own (state, static, client, redis) answers a criteria object through.
+ */
+export interface RecordQueryHelper {
+  /**
+   * Whether one record satisfies the criteria.
+   *
+   * `undefined` as a criteria value is skipped rather than compared — it is what an optional filter
+   * looks like when nothing was chosen, and treating it as "must be undefined" makes an unset
+   * dropdown filter the list down to nothing.
+   *
+   * @throws {UnsupportedArgumentError} on an unknown operator.
+   */
+  matchCriteria: <T extends ResourceRecord>(record: T, criteria?: Criteria<any>) => boolean
+  /** Every record the criteria accepts, in insertion order. */
+  filterRecords: <T extends ResourceRecord>(records: T[], criteria?: Criteria<any>) => T[]
+  /**
+   * Sort a copy. A bare field name is ascending; `{ field, order: 'desc' }` reverses it — the same
+   * meaning every backend gives it, so a sort written for one store orders the same way against
+   * another.
+   */
+  sortRecords: <T extends ResourceRecord>(records: T[], sort?: Sort<any>[]) => T[]
+  /** The first record the criteria accepts, honouring the sort. */
+  firstMatch: <T extends ResourceRecord>(
+    records: T[], where?: Criteria<any>, opts?: { sort?: Sort<any>[] }
+  ) => T | null
+  /**
+   * Filter, sort and page an in-memory record set into the shape every resource answers with.
+   * `size` is opt-in: an in-memory store returns everything when none is asked for.
+   */
+  applyQuery: <T extends ResourceRecord>(
+    records: T[], where?: Criteria<any>, opts?: ListOptions<any>
+  ) => ListResult<T>
+}

package/src/utils/query.ts

@@ -1,5 +1,7 @@
 import { UnsupportedArgumentError } from '../errors.js'
 import type { Criteria, ListOptions, ListResult, ResourceRecord, Sort } from '../types.js'
+import { COMPARISON } from './consts.local.js'
+import type { RecordQueryHelper } from './query/types.js'
 
 /**
  * In-memory evaluation of `Criteria<any>`.
@@ -17,8 +19,6 @@ import type { Criteria, ListOptions, ListResult, ResourceRecord, Sort } from '..
  * - There is no jsonb/column distinction, so a dotted key always reaches into the record.
  */
 
-const COMPARISON = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte'])
-
 /** Dates compare by instant; everything else compares as it is. */
 const comparable = (value: unknown): unknown =>
   value instanceof Date ? value.getTime() : value
@@ -159,119 +159,127 @@ const applyOperators = (value: unknown, spec: Record<string, unknown>): boolean
   return true
 }
 
-/**
- * Whether one record satisfies the criteria.
- *
- * `undefined` as a criteria value is skipped rather than compared — it is what an optional filter
- * looks like when nothing was chosen, and treating it as "must be undefined" makes an unset
- * dropdown filter the list down to nothing.
- *
- * @throws {UnsupportedArgumentError} on an unknown operator.
- */
-export const matchCriteria = <T extends ResourceRecord>(
-  record: T, criteria?: Criteria<any>
-): boolean => {
-  for (const [key, raw] of Object.entries(criteria ?? {})) {
-    if (raw === undefined) {
-      continue
-    }
+export const createRecordQueryHelper = (): RecordQueryHelper => {
+  const matchCriteria = <T extends ResourceRecord>(
+    record: T, criteria?: Criteria<any>
+  ): boolean => {
+    for (const [key, raw] of Object.entries(criteria ?? {})) {
+      if (raw === undefined) {
+        continue
+      }
 
-    if (key === '$and' || key === '$or') {
-      const parts = (Array.isArray(raw) ? raw : [raw]) as Criteria<any>[]
-      if (parts.length < 1) continue
-      const matched = key === '$and'
-        ? parts.every(part => matchCriteria(record, part))
-        : parts.some(part => matchCriteria(record, part))
-      if (!matched) return false
-      continue
-    }
-    if (key === '$not') {
-      if (matchCriteria(record, raw as Criteria<any>)) return false
-      continue
-    }
+      if (key === '$and' || key === '$or') {
+        const parts = (Array.isArray(raw) ? raw : [raw]) as Criteria<any>[]
+        if (parts.length < 1) continue
+        const matched = key === '$and'
+          ? parts.every(part => matchCriteria(record, part))
+          : parts.some(part => matchCriteria(record, part))
+        if (!matched) return false
+        continue
+      }
+      if (key === '$not') {
+        if (matchCriteria(record, raw as Criteria<any>)) return false
+        continue
+      }
 
-    const value = reach(record, key.split('.'))
+      const value = reach(record, key.split('.'))
 
-    if (raw === null) {
-      if (value != null) return false
-      continue
-    }
-    if (isOperatorSpec(raw)) {
-      if (!applyOperators(value, raw as Record<string, unknown>)) return false
-      continue
-    }
-    if (Array.isArray(raw)) {
-      /**
-       * A bare array means "any of these", exactly as it does against a relational store.
-       * Exact array equality stays reachable as `{ $eq: [...] }`.
-       */
-      if (!inList(value, raw)) return false
-      continue
+      if (raw === null) {
+        if (value != null) return false
+        continue
+      }
+      if (isOperatorSpec(raw)) {
+        if (!applyOperators(value, raw as Record<string, unknown>)) return false
+        continue
+      }
+      if (Array.isArray(raw)) {
+        /**
+         * A bare array means "any of these", exactly as it does against a relational store.
+         * Exact array equality stays reachable as `{ $eq: [...] }`.
+         */
+        if (!inList(value, raw)) return false
+        continue
+      }
+      if (!equal(value, raw)) return false
     }
-    if (!equal(value, raw)) return false
+
+    return true
   }
 
-  return true
-}
+  const filterRecords = <T extends ResourceRecord>(
+    records: T[], criteria?: Criteria<any>
+  ): T[] => criteria == null || Object.keys(criteria).length < 1
+      ? [...records]
+      : records.filter(record => matchCriteria(record, criteria))
 
-/** Every record the criteria accepts, in insertion order. */
-export const filterRecords = <T extends ResourceRecord>(
-  records: T[], criteria?: Criteria<any>
-): T[] => criteria == null || Object.keys(criteria).length < 1
-    ? [...records]
-    : records.filter(record => matchCriteria(record, criteria))
+  const sortRecords = <T extends ResourceRecord>(records: T[], sort?: Sort<any>[]): T[] => {
+    if (sort == null || sort.length < 1) {
+      return [...records]
+    }
 
-/**
- * Sort a copy. A bare field name is ascending; `{ field, order: 'desc' }` reverses it — the same
- * meaning every backend gives it, so a sort written for one store orders the same way against
- * another.
- */
-export const sortRecords = <T extends ResourceRecord>(records: T[], sort?: Sort<any>[]): T[] => {
-  if (sort == null || sort.length < 1) {
-    return [...records]
+    const rules = sort.map(entry => typeof entry === 'string'
+      ? { field: entry, desc: false }
+      : { field: entry.field, desc: entry.order === 'desc' })
+
+    return [...records].sort((left, right) => {
+      for (const { field, desc } of rules) {
+        const a = comparable(reach(left, field.split('.')))
+        const b = comparable(reach(right, field.split('.')))
+        if (a == null && b == null) continue
+        /** An absent value sorts last ascending, which is where a reader expects "no value". */
+        if (a == null) return 1
+        if (b == null) return -1
+        if ((a as never) < (b as never)) return desc ? 1 : -1
+        if ((a as never) > (b as never)) return desc ? -1 : 1
+      }
+
+      return 0
+    })
   }
 
-  const rules = sort.map(entry => typeof entry === 'string'
-    ? { field: entry, desc: false }
-    : { field: entry.field, desc: entry.order === 'desc' })
+  const firstMatch = <T extends ResourceRecord>(
+    records: T[], where?: Criteria<any>, opts?: { sort?: Sort<any>[] }
+  ): T | null => sortRecords(filterRecords(records, where), opts?.sort)[0] ?? null
 
-  return [...records].sort((left, right) => {
-    for (const { field, desc } of rules) {
-      const a = comparable(reach(left, field.split('.')))
-      const b = comparable(reach(right, field.split('.')))
-      if (a == null && b == null) continue
-      /** An absent value sorts last ascending, which is where a reader expects "no value". */
-      if (a == null) return 1
-      if (b == null) return -1
-      if ((a as never) < (b as never)) return desc ? 1 : -1
-      if ((a as never) > (b as never)) return desc ? -1 : 1
+  const applyQuery = <T extends ResourceRecord>(
+    records: T[], where?: Criteria<any>, opts?: ListOptions<any>
+  ): ListResult<T> => {
+    const matched = sortRecords(filterRecords(records, where), opts?.sort)
+    const total = matched.length
+    // `size: 0` is the explicit ask for everything — the same meaning the paged backends give it, so
+    // one query object means one thing whichever store answers it. An omitted size is unpaged here.
+    if (opts?.size == null || opts.size === 0) {
+      return { items: matched, total }
     }
+    const page = opts.page ?? 0
+    const from = page * opts.size
 
-    return 0
-  })
+    return { items: matched.slice(from, from + opts.size), total, page, size: opts.size }
+  }
+
+  return { matchCriteria, filterRecords, sortRecords, firstMatch, applyQuery }
 }
 
-/** The first record the criteria accepts, honouring the sort. */
+export const recordQueryHelper = createRecordQueryHelper()
+
+/** @deprecated compat:factory-refactor — use `recordQueryHelper.matchCriteria(…)` */
+export const matchCriteria = <T extends ResourceRecord>(record: T, criteria?: Criteria<any>): boolean =>
+  recordQueryHelper.matchCriteria(record, criteria)
+
+/** @deprecated compat:factory-refactor — use `recordQueryHelper.filterRecords(…)` */
+export const filterRecords = <T extends ResourceRecord>(records: T[], criteria?: Criteria<any>): T[] =>
+  recordQueryHelper.filterRecords(records, criteria)
+
+/** @deprecated compat:factory-refactor — use `recordQueryHelper.sortRecords(…)` */
+export const sortRecords = <T extends ResourceRecord>(records: T[], sort?: Sort<any>[]): T[] =>
+  recordQueryHelper.sortRecords(records, sort)
+
+/** @deprecated compat:factory-refactor — use `recordQueryHelper.firstMatch(…)` */
 export const firstMatch = <T extends ResourceRecord>(
   records: T[], where?: Criteria<any>, opts?: { sort?: Sort<any>[] }
-): T | null => sortRecords(filterRecords(records, where), opts?.sort)[0] ?? null
+): T | null => recordQueryHelper.firstMatch(records, where, opts)
 
-/**
- * Filter, sort and page an in-memory record set into the shape every resource answers with.
- * `size` is opt-in: an in-memory store returns everything when none is asked for.
- */
+/** @deprecated compat:factory-refactor — use `recordQueryHelper.applyQuery(…)` */
 export const applyQuery = <T extends ResourceRecord>(
   records: T[], where?: Criteria<any>, opts?: ListOptions<any>
-): ListResult<T> => {
-  const matched = sortRecords(filterRecords(records, where), opts?.sort)
-  const total = matched.length
-  // `size: 0` is the explicit ask for everything — the same meaning the paged backends give it, so
-  // one query object means one thing whichever store answers it. An omitted size is unpaged here.
-  if (opts?.size == null || opts.size === 0) {
-    return { items: matched, total }
-  }
-  const page = opts.page ?? 0
-  const from = page * opts.size
-
-  return { items: matched.slice(from, from + opts.size), total, page, size: opts.size }
-}
+): ListResult<T> => recordQueryHelper.applyQuery(records, where, opts)

package/src/utils.ts

@@ -0,0 +1,26 @@
+import type { ListResult, ResourceRecord } from './types.js'
+import type { JSONSchemaType } from 'ajv'
+
+export const createListSchema = <T extends ResourceRecord>(schema: JSONSchemaType<T>): JSONSchemaType<ListResult<T>> => ({
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        ...schema,
+        type: 'object',
+        properties: {
+          id: { type: 'string', nullable: true },
+          ...schema.properties
+        },
+        ...(schema.required ? { required: [...schema.required] } : undefined),
+        additionalProperties: false,
+      }
+    },
+    total: { type: 'number' },
+    page: { type: 'number', nullable: true },
+    size: { type: 'number', nullable: true }
+  },
+  required: ['items', 'total'],
+  additionalProperties: false,
+})

package/tests/errors.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test'
+import { ResilientError } from '@owlmeans/error'
+import * as errors from '../src/errors.js'
+
+/**
+ * The status an HTTP boundary (`@owlmeans/server-api` `errorStatus`) reads off a class: a static
+ * `httpStatus` inherited through the constructor chain. A refusal of the caller's request declares
+ * a 4xx; a fault declares nothing and answers 500.
+ */
+const statusOf = (error: Error): unknown => (error.constructor as { httpStatus?: unknown }).httpStatus
+
+const DECLARED: Record<string, number | undefined> = {
+  ResourceError: undefined,
+  UnknownRecordError: 404,
+  RecordExists: 409,
+  MisshapedRecord: undefined,
+  RecordUpdateFailed: undefined,
+  UnsupportedArgumentError: undefined,
+  UnsupportedMethodError: undefined,
+  MigrationError: undefined,
+  MigrationConflict: undefined,
+}
+
+const classes = Object.entries(errors).filter(([, value]) =>
+  typeof value === 'function' && value.prototype instanceof ResilientError
+) as [string, new (message: string) => ResilientError][]
+
+describe('resource errors — declared HTTP statuses', () => {
+  test('every class of the family has decided its status', () => {
+    expect(classes.map(([name]) => name).sort()).toEqual(Object.keys(DECLARED).sort())
+  })
+
+  test('an absent record is 404, a taken id or key 409; faults declare nothing', () => {
+    for (const [name, Class] of classes) {
+      expect([name, statusOf(new Class('x'))]).toEqual([name, DECLARED[name]])
+    }
+  })
+
+  test('an error rebuilt from its marshalled form keeps its class and its status', () => {
+    for (const [name, Class] of classes) {
+      const back = ResilientError.ensure(new Class('x').marshal())
+      expect([name, back.constructor === Class, statusOf(back)]).toEqual([name, true, DECLARED[name]])
+    }
+  })
+})
+
+describe('UnknownRecordError.id', () => {
+  test('is everything after the first separator, however many the id carries', () => {
+    expect(new errors.UnknownRecordError('abc').id).toBe('abc')
+    expect(new errors.UnknownRecordError('shelf/3/hammer').id).toBe('shelf/3/hammer')
+    expect(new errors.UnknownRecordError('{"url":"https://example.org/a"}').id)
+      .toBe('{"url":"https://example.org/a"}')
+  })
+
+  test('survives a marshal round trip', () => {
+    const back = ResilientError.ensure(new errors.UnknownRecordError('shelf/3').marshal())
+    expect(back).toBeInstanceOf(errors.UnknownRecordError)
+    expect((back as errors.UnknownRecordError).id).toBe('shelf/3')
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": [
+      "bun"
+    ],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": [
+    "./**/*",
+    "../src/**/*"
+  ]
+}

package/tsconfig.json

@@ -6,5 +6,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }