urlToFields

We used to have urlToUserFields, with the idea of having a separate one for each type, but as you get into relationships and compound documents, it's more often the case where we want all of the sparse fieldset data for all types at once. This stores that data in a Fields interface, and establishes a urlToFields method that can be expanded to handle additional types.

Author: jefgodesky

collections/users/controller.ts

@@ -3,12 +3,12 @@ import UserRepository from './repository.ts'
 import sendJSON from '../../utils/send-json.ts'
 import sendNoContent from '../../utils/send-no-content.ts'
 import userToUserResponse from '../../utils/transformers/user-to/user-response.ts'
-import urlToUserFields from '../../utils/transformers/url-to/user-fields.ts'
+import urlToFields from '../../utils/transformers/url-to/fields.ts'
 
 class UserController {
   static get (ctx: Context, url?: URL) {
     const fieldSrc = url ?? ctx
-    const fields = urlToUserFields(fieldSrc)
+    const fields = urlToFields(fieldSrc)
     const res = userToUserResponse(ctx.state.user, fields)
     sendJSON(ctx, res)
   }
@@ -25,7 +25,7 @@ class UserController {
     await users.save(user)
 
     const fieldSrc = url ?? ctx
-    const fields = urlToUserFields(fieldSrc)
+    const fields = urlToFields(fieldSrc)
     const res = userToUserResponse(user, fields)
     sendJSON(ctx, res)
   }

types/fields.ts

@@ -1,5 +1,15 @@
-import { type UserAttributesKeys } from './user-attributes.ts'
+import { type UserAttributesKeys, userAttributes } from './user-attributes.ts'
 
 export default interface Fields {
-  users: UserAttributesKeys[]
+  users: readonly UserAttributesKeys[]
 }
+
+const createFields = (overrides?: Partial<Fields>): Fields => {
+  const defaultFields: Fields = {
+    users: userAttributes
+  }
+
+  return { ...defaultFields, ...overrides }
+}
+
+export { createFields }

types/user-attributes.ts

@@ -6,9 +6,8 @@ export default interface UserAttributes {
   username?: string
 }
 
-const allUserAttributes = ['name', 'username'] as const
-const publicUserAttributes = ['name', 'username'] as const
-type UserAttributesKeys = (typeof allUserAttributes)[number]
+const userAttributes = ['name', 'username'] as const
+type UserAttributesKeys = (typeof userAttributes)[number]
 
 const createUserAttributes = (overrides?: Partial<UserAttributes>): UserAttributes => {
   const defaultUserAttributes: UserAttributes = {
@@ -19,6 +18,7 @@ const createUserAttributes = (overrides?: Partial<UserAttributes>): UserAttribut
   return { ...defaultUserAttributes, ...overrides }
 }
 
+// deno-lint-ignore no-explicit-any
 const isUserAttributes = (candidate: any): candidate is UserAttributes => {
   if (!isObject(candidate)) return false
   const obj = candidate as Record<string, unknown>
@@ -30,7 +30,6 @@ const isUserAttributes = (candidate: any): candidate is UserAttributes => {
 export {
   createUserAttributes,
   isUserAttributes,
-  allUserAttributes,
-  publicUserAttributes,
+  userAttributes,
   type UserAttributesKeys
 }

utils/transformers/url-to/fields.test.ts

@@ -0,0 +1,27 @@
+import { describe, it } from 'jsr:@std/testing/bdd'
+import { expect } from 'jsr:@std/expect'
+import { createUserAttributes, userAttributes } from '../../../types/user-attributes.ts'
+import getAllFieldCombinations from '../../testing/get-all-field-combinations.ts'
+import getRoot from '../../get-root.ts'
+import urlToFields from './fields.ts'
+
+describe('urlToFields', () => {
+  describe('User fields', () => {
+    it('returns public attributes if there is no fields[users] parameter', () => {
+      const url = new URL(`${getRoot()}/users`)
+      const actual = urlToFields(url)
+      expect(actual.users).toEqual(userAttributes)
+    })
+
+    it('returns the fields specified', () => {
+      const attributes = createUserAttributes()
+      const objects = getAllFieldCombinations(attributes)
+      for (const object of objects) {
+        const fields = Object.keys(object)
+        const url = new URL(`${getRoot()}/users?this=1&fields[users]=${fields.join(',')}&that=2`)
+        const actual = urlToFields(url)
+        expect(actual.users).toEqual(fields)
+      }
+    })
+  })
+})

utils/transformers/url-to/fields.ts

@@ -0,0 +1,21 @@
+import { Context } from '@oak/oak'
+import { intersect } from '@std/collections'
+import Fields, { createFields } from '../../../types/fields.ts'
+
+const urlToFields = (input: Context | URL): Fields => {
+  const url = (input as Context)?.request?.url ?? input
+  const fields = createFields()
+
+  const updateField = <K extends keyof Fields>(key: K) => {
+    const param = url.searchParams.get(`fields[${key}]`)
+    if (param !== null) {
+      const requested = param.split(',').map(field => field.trim()) as Fields[K]
+      fields[key] = intersect(requested, fields[key]) as Fields[K]
+    }
+  }
+
+  (Object.keys(fields) as (keyof Fields)[]).forEach(updateField)
+  return fields
+}
+
+export default urlToFields

utils/transformers/url-to/user-fields.test.ts

@@ -1,7 +1,8 @@
 import { describe, it } from 'jsr:@std/testing/bdd'
 import { expect } from 'jsr:@std/expect'
+import { createFields } from '../../../types/fields.ts'
 import { createUser } from '../../../types/user.ts'
-import { type UserAttributesKeys, allUserAttributes, createUserAttributes }  from '../../../types/user-attributes.ts'
+import { type UserAttributesKeys, userAttributes, createUserAttributes }  from '../../../types/user-attributes.ts'
 import getRoot from '../../get-root.ts'
 import getAllFieldCombinations from '../../testing/get-all-field-combinations.ts'
 import userToIncludedResource from './included-resource.ts'
@@ -29,13 +30,13 @@ describe('userToIncludedResource', () => {
   it('can return a sparse fieldset', () => {
     const objects = getAllFieldCombinations(attributes)
     for (const object of objects) {
-      const fields = Object.keys(object) as UserAttributesKeys[]
-      const excluded = allUserAttributes.filter(attr => !fields.includes(attr))
+      const fields = createFields({ users: Object.keys(object) as UserAttributesKeys[] })
+      const excluded = userAttributes.filter(attr => !fields.users.includes(attr))
       const actual = userToIncludedResource(user, fields)
       const attributes = actual.attributes!
 
-      expect(Object.keys(attributes)).toHaveLength(fields.length)
-      for (const field of fields) expect(attributes[field]).toBe(user[field])
+      expect(Object.keys(attributes)).toHaveLength(fields.users.length)
+      for (const field of fields.users) expect(attributes[field]).toBe(user[field])
       for (const ex of excluded) expect(attributes[ex]).not.toBeDefined()
     }
   })

utils/transformers/url-to/user-fields.ts

@@ -1,10 +1,10 @@
+import type Fields from '../../../types/fields.ts'
 import type User from '../../../types/user.ts'
 import type UserResource from '../../../types/user-resource.ts'
-import { type UserAttributesKeys, publicUserAttributes } from '../../../types/user-attributes.ts'
 import userToLink from './link.ts'
 import userToUserAttributes from './user-attributes.ts'
 
-const userToIncludedResource = (user: User, fields: readonly UserAttributesKeys[] = publicUserAttributes): UserResource => {
+const userToIncludedResource = (user: User, fields?: Fields): UserResource => {
   return {
     links: {
       self: userToLink(user)

utils/transformers/user-to/included-resource.test.ts

@@ -1,7 +1,8 @@
 import { describe, it } from 'jsr:@std/testing/bdd'
 import { expect } from 'jsr:@std/expect'
+import { createFields } from '../../../types/fields.ts'
 import { createUser } from '../../../types/user.ts'
-import { type UserAttributesKeys, allUserAttributes, createUserAttributes } from '../../../types/user-attributes.ts'
+import { type UserAttributesKeys, userAttributes, createUserAttributes } from '../../../types/user-attributes.ts'
 import getAllFieldCombinations from '../../testing/get-all-field-combinations.ts'
 import userToUserAttributes from './user-attributes.ts'
 
@@ -19,12 +20,12 @@ describe('userToUserAttributes', () => {
   it('can return a sparse fieldset', () => {
     const objects = getAllFieldCombinations(attributes)
     for (const object of objects) {
-      const fields = Object.keys(object) as UserAttributesKeys[]
-      const excluded = allUserAttributes.filter(attr => !fields.includes(attr))
+      const fields = createFields({ users: Object.keys(object) as UserAttributesKeys[] })
+      const excluded = userAttributes.filter(attr => !fields.users.includes(attr))
       const actual = userToUserAttributes(user, fields)
 
-      expect(Object.keys(actual)).toHaveLength(fields.length)
-      for (const field of fields) expect(actual[field]).toBe(user[field])
+      expect(Object.keys(actual)).toHaveLength(fields.users.length)
+      for (const field of fields.users) expect(actual[field]).toBe(user[field])
       for (const ex of excluded) expect(actual[ex]).not.toBeDefined()
     }
   })