@feathersjs/adapter-commons 5.0.0-pre.3 → 5.0.0-pre.30

package/src/declarations.ts

@@ -0,0 +1,156 @@
+import { Query, Params, Paginated, Id, NullableId } from '@feathersjs/feathers'
+
+export type FilterQueryOptions = {
+  filters?: FilterSettings
+  operators?: string[]
+  paginate?: PaginationParams
+}
+
+export type QueryFilter = (value: any, options: FilterQueryOptions) => any
+
+export type FilterSettings = {
+  [key: string]: QueryFilter | true
+}
+
+export interface PaginationOptions {
+  default?: number
+  max?: number
+}
+
+export type PaginationParams = false | PaginationOptions
+
+export interface AdapterServiceOptions {
+  /**
+   * Whether to allow multiple updates for everything (`true`) or specific methods (e.g. `['create', 'remove']`)
+   */
+  multi?: boolean | string[]
+  /**
+   * The name of the id property
+   */
+  id?: string
+  /**
+   * Pagination settings for this service
+   */
+  paginate?: PaginationParams
+  /**
+   * A list of additional property query operators to allow in a query
+   */
+  operators?: string[]
+  /**
+   * An object of additional top level query filters, e.g. `{ $populate: true }`
+   * Can also be a converter function like `{ $ignoreCase: (value) => value === 'true' ? true : false }`
+   */
+  filters?: FilterSettings
+  /**
+   * @deprecated Use service `events` option when registering the service with `app.use`.
+   */
+  events?: string[]
+  /**
+   * @deprecated renamed to `operators`.
+   */
+  whitelist?: string[]
+}
+
+export interface AdapterQuery extends Query {
+  $limit?: number
+  $skip?: number
+  $select?: string[]
+  $sort?: { [key: string]: 1 | -1 }
+}
+/**
+ * Additional `params` that can be passed to an adapter service method call.
+ */
+export interface AdapterParams<
+  Q = AdapterQuery,
+  A extends Partial<AdapterServiceOptions> = Partial<AdapterServiceOptions>
+> extends Params<Q> {
+  adapter?: A
+  paginate?: PaginationParams
+}
+
+/**
+ * Hook-less (internal) service methods. Directly call database adapter service methods
+ * without running any service-level hooks or sanitization. This can be useful if you need the raw data
+ * from the service and don't want to trigger any of its hooks.
+ *
+ * Important: These methods are only available internally on the server, not on the client
+ * side and only for the Feathers database adapters.
+ *
+ * These methods do not trigger events.
+ *
+ * @see {@link https://docs.feathersjs.com/guides/migrating.html#hook-less-service-methods}
+ */
+export interface InternalServiceMethods<T = any, D = Partial<T>, P extends AdapterParams = AdapterParams> {
+  /**
+   * Retrieve all resources from this service.
+   * Does not sanitize the query and should only be used on the server.
+   *
+   * @param _params - Service call parameters {@link Params}
+   */
+  $find(_params?: P & { paginate?: PaginationOptions }): Promise<Paginated<T>>
+  $find(_params?: P & { paginate: false }): Promise<T[]>
+  $find(params?: P): Promise<T[] | Paginated<T>>
+
+  /**
+   * Retrieve a single resource matching the given ID, skipping any service-level hooks.
+   * Does not sanitize the query and should only be used on the server.
+   *
+   * @param id - ID of the resource to locate
+   * @param params - Service call parameters {@link Params}
+   * @see {@link HookLessServiceMethods}
+   * @see {@link https://docs.feathersjs.com/api/services.html#get-id-params|Feathers API Documentation: .get(id, params)}
+   */
+  $get(id: Id, params?: P): Promise<T>
+
+  /**
+   * Create a new resource for this service, skipping any service-level hooks.
+   * Does not sanitize data or checks if multiple updates are allowed and should only be used on the server.
+   *
+   * @param data - Data to insert into this service.
+   * @param params - Service call parameters {@link Params}
+   * @see {@link HookLessServiceMethods}
+   * @see {@link https://docs.feathersjs.com/api/services.html#create-data-params|Feathers API Documentation: .create(data, params)}
+   */
+  $create(data: Partial<D>, params?: P): Promise<T>
+  $create(data: Partial<D>[], params?: P): Promise<T[]>
+  $create(data: Partial<D> | Partial<D>[], params?: P): Promise<T | T[]>
+
+  /**
+   * Completely replace the resource identified by id, skipping any service-level hooks.
+   * Does not sanitize data or query and should only be used on the server.
+   *
+   * @param id - ID of the resource to be updated
+   * @param data - Data to be put in place of the current resource.
+   * @param params - Service call parameters {@link Params}
+   * @see {@link HookLessServiceMethods}
+   * @see {@link https://docs.feathersjs.com/api/services.html#update-id-data-params|Feathers API Documentation: .update(id, data, params)}
+   */
+  $update(id: Id, data: D, params?: P): Promise<T>
+
+  /**
+   * Merge any resources matching the given ID with the given data, skipping any service-level hooks.
+   * Does not sanitize the data or query and should only be used on the server.
+   *
+   * @param id - ID of the resource to be patched
+   * @param data - Data to merge with the current resource.
+   * @param params - Service call parameters {@link Params}
+   * @see {@link HookLessServiceMethods}
+   * @see {@link https://docs.feathersjs.com/api/services.html#patch-id-data-params|Feathers API Documentation: .patch(id, data, params)}
+   */
+  $patch(id: null, data: Partial<D>, params?: P): Promise<T[]>
+  $patch(id: Id, data: Partial<D>, params?: P): Promise<T>
+  $patch(id: NullableId, data: Partial<D>, params?: P): Promise<T | T[]>
+
+  /**
+   * Remove resources matching the given ID from the this service, skipping any service-level hooks.
+   * Does not sanitize query and should only be used on the server.
+   *
+   * @param id - ID of the resource to be removed
+   * @param params - Service call parameters {@link Params}
+   * @see {@link HookLessServiceMethods}
+   * @see {@link https://docs.feathersjs.com/api/services.html#remove-id-params|Feathers API Documentation: .remove(id, params)}
+   */
+  $remove(id: null, params?: P): Promise<T[]>
+  $remove(id: Id, params?: P): Promise<T>
+  $remove(id: NullableId, params?: P): Promise<T | T[]>
+}

package/src/index.ts

@@ -1,32 +1,29 @@
-import { _ } from '@feathersjs/commons';
+import { _ } from '@feathersjs/commons'
+import { Params } from '@feathersjs/feathers'
 
-export { AdapterService, InternalServiceMethods, ServiceOptions, Paginated } from './service';
-export { filterQuery, FILTERS, OPERATORS } from './filter-query';
-export * from './sort';
+export * from './declarations'
+export * from './service'
+export { filterQuery, FILTERS, OPERATORS } from './query'
+export * from './sort'
 
 // Return a function that filters a result object or array
 // and picks only the fields passed as `params.query.$select`
 // and additional `otherFields`
-export function select (params: any, ...otherFields: any[]) {
-  const fields = params && params.query && params.query.$select;
+export function select(params: Params, ...otherFields: string[]) {
+  const queryFields: string[] | undefined = params?.query?.$select
 
-  if (Array.isArray(fields) && otherFields.length) {
-    fields.push(...otherFields);
+  if (!queryFields) {
+    return (result: any) => result
   }
 
-  const convert = (result: any) => {
-    if (!Array.isArray(fields)) {
-      return result;
-    }
-
-    return _.pick(result, ...fields);
-  };
+  const resultFields = queryFields.concat(otherFields)
+  const convert = (result: any) => _.pick(result, ...resultFields)
 
   return (result: any) => {
     if (Array.isArray(result)) {
-      return result.map(convert);
+      return result.map(convert)
     }
 
-    return convert(result);
-  };
+    return convert(result)
+  }
 }

package/src/query.ts

@@ -0,0 +1,137 @@
+import { _ } from '@feathersjs/commons'
+import { BadRequest } from '@feathersjs/errors'
+import { Query } from '@feathersjs/feathers'
+import { FilterQueryOptions, FilterSettings } from './declarations'
+
+const parse = (value: any) => (typeof value !== 'undefined' ? parseInt(value, 10) : value)
+
+const isPlainObject = (value: any) => _.isObject(value) && value.constructor === {}.constructor
+
+const validateQueryProperty = (query: any, operators: string[] = []): Query => {
+  if (!isPlainObject(query)) {
+    return query
+  }
+
+  for (const key of Object.keys(query)) {
+    if (key.startsWith('$') && !operators.includes(key)) {
+      throw new BadRequest(`Invalid query parameter ${key}`, query)
+    }
+
+    const value = query[key]
+
+    if (isPlainObject(value)) {
+      query[key] = validateQueryProperty(value, operators)
+    }
+  }
+
+  return {
+    ...query
+  }
+}
+
+const getFilters = (query: Query, settings: FilterQueryOptions) => {
+  const filterNames = Object.keys(settings.filters)
+
+  return filterNames.reduce((current, key) => {
+    const queryValue = query[key]
+    const filter = settings.filters[key]
+
+    if (filter) {
+      const value = typeof filter === 'function' ? filter(queryValue, settings) : queryValue
+
+      if (value !== undefined) {
+        current[key] = value
+      }
+    }
+
+    return current
+  }, {} as { [key: string]: any })
+}
+
+const getQuery = (query: Query, settings: FilterQueryOptions) => {
+  const keys = Object.keys(query).concat(Object.getOwnPropertySymbols(query) as any as string[])
+
+  return keys.reduce((result, key) => {
+    if (typeof key === 'string' && key.startsWith('$')) {
+      if (settings.filters[key] === undefined) {
+        throw new BadRequest(`Invalid filter value ${key}`)
+      }
+    } else {
+      result[key] = validateQueryProperty(query[key], settings.operators)
+    }
+
+    return result
+  }, {} as Query)
+}
+
+export const OPERATORS = ['$in', '$nin', '$lt', '$lte', '$gt', '$gte', '$ne', '$or']
+
+export const FILTERS: FilterSettings = {
+  $skip: (value: any) => parse(value),
+  $sort: (sort: any): { [key: string]: number } => {
+    if (typeof sort !== 'object' || Array.isArray(sort)) {
+      return sort
+    }
+
+    return Object.keys(sort).reduce((result, key) => {
+      result[key] = typeof sort[key] === 'object' ? sort[key] : parse(sort[key])
+
+      return result
+    }, {} as { [key: string]: number })
+  },
+  $limit: (_limit: any, { paginate }: FilterQueryOptions) => {
+    const limit = parse(_limit)
+
+    if (paginate && (paginate.default || paginate.max)) {
+      const base = paginate.default || 0
+      const lower = typeof limit === 'number' && !isNaN(limit) && limit >= 0 ? limit : base
+      const upper = typeof paginate.max === 'number' ? paginate.max : Number.MAX_VALUE
+
+      return Math.min(lower, upper)
+    }
+
+    return limit
+  },
+  $select: (select: any) => {
+    if (Array.isArray(select)) {
+      return select.map((current) => `${current}`)
+    }
+
+    return select
+  },
+  $or: (or: any, { operators }: FilterQueryOptions) => {
+    if (Array.isArray(or)) {
+      return or.map((current) => validateQueryProperty(current, operators))
+    }
+
+    return or
+  }
+}
+
+/**
+ * Converts Feathers special query parameters and pagination settings
+ * and returns them separately as `filters` and the rest of the query
+ * as `query`. `options` also gets passed the pagination settings and
+ * a list of additional `operators` to allow when querying properties.
+ *
+ * @param query The initial query
+ * @param options Options for filtering the query
+ * @returns An object with `query` which contains the query without `filters`
+ * and `filters` which contains the converted values for each filter.
+ */
+export function filterQuery(_query: Query, options: FilterQueryOptions = {}) {
+  const query = _query || {}
+  const settings = {
+    ...options,
+    filters: {
+      ...FILTERS,
+      ...options.filters
+    },
+    operators: OPERATORS.concat(options.operators || [])
+  }
+
+  return {
+    filters: getFilters(query, settings),
+    query: getQuery(query, settings)
+  }
+}