feat: omitServerProps helper function

package.json

@@ -63,6 +63,7 @@
   "dependencies": {
     "@comapeo/geometry": "^1.0.2",
     "compact-encoding": "^2.12.0",
+    "filter-obj": "^6.1.0",
     "protobufjs": "^7.2.5",
     "type-fest": "^4.26.0"
   },

scripts/lib/generate-jsonschema-exports.js

@@ -48,6 +48,7 @@ export async function generateJSONSchemaExports(jsonSchemas) {
 
   return `import { type JSONSchema7 } from 'json-schema'
 import { type SchemaNameAll } from './types.js'
+import { type MapeoCommon } from './schema/index.js'
 import { type ReadonlyDeep } from 'type-fest'
 
 declare module 'json-schema' {
@@ -58,6 +59,8 @@ declare module 'json-schema' {
 
 type SchemaRecord = Record<SchemaNameAll, ReadonlyDeep<JSONSchema7>>
 
+export const commonSchema = ${printf(jsonSchemas.values.common)} as const satisfies ReadonlyDeep<JSONSchema7>
+
 export const docSchemas = ${printf(docSchemas)} as const satisfies SchemaRecord
 
 export const dereferencedDocSchemas = ${printf(

src/index.ts

@@ -6,6 +6,7 @@ export {
   getVersionId,
   parseVersionId,
   valueOf,
+  omitServerProps,
   type VersionIdObject,
 } from './lib/utils.js'
 

src/lib/utils.ts

@@ -1,9 +1,12 @@
+import { excludeKeys } from 'filter-obj'
 import { type ProtoTypeNames } from '../proto/types.js'
 import {
+  type FilterBySchemaName,
+  type MapeoCommon,
   type MapeoDoc,
   type MapeoValue,
-  type FilterBySchemaName,
 } from '../types.js'
+import { commonSchema } from '../schemas.js'
 import { omit } from './omit.js'
 
 export function getOwn<T extends object, K extends keyof T>(
@@ -79,6 +82,10 @@ export function parseVersionId(versionId: string): VersionIdObject {
   return { coreDiscoveryKey, index }
 }
 
+/**
+ * Get the value of a document, excluding server-managed properties.
+ * @deprecated Use the more flexible `omitServerProps` instead
+ */
 export function valueOf<TDoc extends MapeoDoc>(
   doc: TDoc & { forks?: string[] }
 ): FilterBySchemaName<MapeoValue, TDoc['schemaName']> {
@@ -93,3 +100,22 @@ export function valueOf<TDoc extends MapeoDoc>(
     'deleted',
   ]) as any
 }
+
+// Casting this type because we _know_ that commonSchema.properties does not
+// have additional keys, unlike situations described in
+// https://stackoverflow.com/a/55012175
+const commonSchemaKeys = Object.keys(commonSchema.properties).filter(
+  (key) => key !== 'schemaName'
+) as Array<keyof Omit<MapeoCommon, 'schemaName'>>
+
+const keysToExclude = [...commonSchemaKeys, 'forks'] as const
+
+/**
+ * Omit server-managed properties from a document, such as `createdBy`,
+ * `createdAt`, etc. These properties cannot be modified by the client.
+ */
+export function omitServerProps<TDoc extends MapeoCommon>(
+  doc: TDoc & { forks?: string[] }
+) {
+  return excludeKeys(doc, keysToExclude)
+}