@cero-base/core 0.2.0 → 0.4.0

package/src/lib/schema.js

@@ -1,450 +1,68 @@
-import Hyperschema from 'hyperschema'
-import { extendIdentitySchema, extendIdentityDispatch } from '@lekinox/cero/src/identity/schema.js'
-import { extendRoomSchema, extendRoomDispatch } from '@lekinox/cero/src/room/schema.js'
-import { singular, toFields, scopeNs, isLocal, isPrivate, isShared } from './utils.js'
-import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
+import { CeroError } from './errors.js'
+import { SINGLE, COLLECTION, ACTION } from './constants.js'
 
-// Built-in collections inherited from cero. Names map to:
-//   - scope: private = identity-replicated, shared = room-replicated
-//   - type:  singular type name in cero's schema (e.g. 'member' for 'members')
-//   - key:   primary key fields (empty array = single-row collection, e.g. profile)
-//
-// Whether each built-in supports add/set/del is DERIVED from cero's dispatch
-// table at schema-build time (see ceroDispatches), not hardcoded here.
-const BUILTINS = {
-  members: { scope: SCOPE_SHARED, type: 'member', key: ['id'] },
-  profile: { scope: SCOPE_PRIVATE, type: 'profile', key: [] },
-  devices: { scope: SCOPE_PRIVATE, type: 'device', key: ['id'] },
-  rooms: { scope: SCOPE_PRIVATE, type: 'room', key: ['id'] },
-  invites: { scope: SCOPE_PRIVATE, type: 'invite', key: ['id'] },
-  mirrors: { scope: SCOPE_PRIVATE, type: 'mirror', key: ['key'] },
-  settings: { scope: SCOPE_PRIVATE, type: 'setting', key: ['key'] }
-}
-
-// Local-scope built-ins cero registers in @local/* — exposed to apps via
-// db.local.collection(name). Distinct from BUILTINS (which are private/shared).
-const LOCAL_BUILTINS = {
-  identity: { type: 'identity', key: [] },
-  rooms: { type: 'room', key: ['key'] },
-  files: { type: 'file', key: ['key', 'blob.blockOffset'] },
-  settings: { type: 'setting', key: ['key'] },
-  counters: { type: 'counter', key: ['name'] }
-}
-
-// One in-memory Hyperschema per (scope, ns) — built once by running cero's
-// extender and reused for every type lookup. The extender registers all
-// built-in types in the namespace; baseFieldsOf just reads them back.
-const schemaCache = new Map()
-function builtinSchema(scope, nsName) {
-  const key = `${scope}:${nsName}`
-  let schema = schemaCache.get(key)
-  if (schema) return schema
-
-  schema = new Hyperschema()
-  const ns = schema.namespace(nsName)
-  if (scope === SCOPE_SHARED) {
-    extendRoomSchema(schema, ns)
-  } else {
-    extendIdentitySchema(schema, ns)
-  }
-  schemaCache.set(key, schema)
-  return schema
-}
-
-function baseFieldsOf(scope, nsName, typeName) {
-  const type = builtinSchema(scope, nsName).types.get(`@${nsName}/${typeName}`)
-  if (!type) throw new Error(`Built-in type '${typeName}' not found in cero schema`)
-  return type.toJSON().fields
-}
-
-// Cache of dispatch names cero registers per scope. Runs cero's extender
-// against a stub namespace that just captures register() calls.
-const dispatchCache = new Map()
-function ceroDispatches(scope) {
-  if (dispatchCache.has(scope)) return dispatchCache.get(scope)
-  const captured = new Set()
-  const stubNs = {
-    name: scope === SCOPE_SHARED ? 'room' : 'identity',
-    register: (desc) => captured.add(desc.name)
-  }
-  if (scope === SCOPE_SHARED) {
-    extendRoomDispatch(null, stubNs)
-  } else {
-    extendIdentityDispatch(null, stubNs)
-  }
-  dispatchCache.set(scope, captured)
-  return captured
-}
+/**
+ * @typedef {{ prim: string }} Prim
+ * @typedef {{ kind: 'single' | 'collection' | 'action', fields: Record<string, Prim> }} TypeDef
+ * @typedef {{ [name: string]: TypeDef | Record<string, TypeDef> } & { local?: Record<string, TypeDef> }} SchemaDefs
+ * @typedef {{ defs: SchemaDefs }} Schema
+ */
 
-// Does cero have an `add-${type}` dispatch for this built-in?
-function ceroHasAdd(scope, typeName) {
-  return ceroDispatches(scope).has(`add-${typeName}`)
-}
+/** @param {string} name @returns {Prim} */
+const prim = (name) => ({ prim: name })
 
 /**
- * Type helpers for defining schema fields
- * Usage: { name: t.string, count: t.int, active: t.bool }
+ * Schema DSL. Primitive field types and kind-constructors used to describe
+ * a database's tables before the builder turns them into a wire spec.
  */
 export const t = {
-  string: { type: 'string', required: true },
-  int: { type: 'int', required: true },
-  uint: { type: 'uint', required: true },
-  float: { type: 'float', required: true },
-  bool: { type: 'bool', required: true },
-  buffer: { type: 'buffer', required: true },
-  fixed32: { type: 'fixed32', required: true },
-  json: { type: 'json', required: true },
-
-  optional: (field) => ({ ...field, required: false }),
-  array: (field) => ({ ...field, array: true }),
-  ref: (collection) => ({ type: 'string', required: true, ref: collection })
-}
-
-function schemaFields(def) {
-  const fields = toFields(def.fields)
-  // every type gets index for range queries / pagination (assigned by cero's Base)
-  fields.push({ name: 'index', type: 'uint', required: false })
-  if (def.timestamps) {
-    fields.push({ name: 'createdAt', type: 'uint', required: true })
-    fields.push({ name: 'updatedAt', type: 'uint', required: false })
+  string: prim('string'),
+  uint: prim('uint'),
+  int: prim('int'),
+  bool: prim('bool'),
+  bytes: prim('bytes'),
+  json: prim('json'),
+  fixed32: prim('fixed32'),
+  fixed64: prim('fixed64'),
+
+  /**
+   * Single-row table (one record, set/get by name).
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  single(fields) {
+    return { kind: SINGLE, fields }
+  },
+
+  /**
+   * Multi-row table keyed by `id`.
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  collection(fields) {
+    return { kind: COLLECTION, fields }
+  },
+
+  /**
+   * RPC-style mutation that doesn't persist a row.
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  action(fields) {
+    return { kind: ACTION, fields }
   }
-  return fields
-}
-
-function inputFields(def) {
-  return toFields(def.fields).map((f) => ({ ...f, required: false }))
 }
 
-function delFields(def) {
-  const keys = {}
-  for (const k of def.key || ['id']) keys[k] = def.fields[k]
-  return toFields(keys)
-}
-
-t.schema = defineSchema
-
-export function defineSchema(collections, opts = {}) {
-  const entries = Object.entries(collections)
-
-  // Validate built-in entries: user can't override fixed metadata (key, scope, timestamps).
-  for (const [name, def] of entries) {
-    if (!BUILTINS[name]) continue
-    if (def.key !== undefined) {
-      throw new Error(`'${name}' is a built-in; key is fixed and cannot be set`)
-    }
-    if (def.scope !== undefined && def.scope !== BUILTINS[name].scope) {
-      throw new Error(
-        `'${name}' is a built-in with scope '${BUILTINS[name].scope}'; cannot override`
-      )
-    }
-    if (def.timestamps !== undefined) {
-      throw new Error(`'${name}' is a built-in; timestamps is fixed and cannot be set`)
-    }
-  }
-
-  // Type name resolution: built-ins use cero's singular type name, user collections use singular(plural).
-  const types = new Map([
-    // Pre-populate with built-ins so they resolve even when user didn't declare them.
-    ...Object.entries(BUILTINS).map(([name, info]) => [name, info.type]),
-    ...entries.map(([name]) => [name, BUILTINS[name]?.type || singular(name)])
-  ])
-
-  const getScope = ([name, def]) =>
-    BUILTINS[name] ? BUILTINS[name].scope : def.scope || SCOPE_PRIVATE
-  const localEntries = entries.filter((e) => getScope(e) === SCOPE_LOCAL)
-  const privateEntries = entries.filter((e) => getScope(e) === SCOPE_PRIVATE)
-  const sharedEntries = entries.filter((e) => getScope(e) === SCOPE_SHARED)
-
-  const nsFor = (scope) => (scope === SCOPE_SHARED && opts.namespace) || scopeNs(scope)
-
-  return {
-    namespace: opts.namespace || null,
-    collections,
-    types,
-
-    getScope(collection) {
-      if (BUILTINS[collection]) return BUILTINS[collection].scope
-      const def = collections[collection]
-      return def ? def.scope || SCOPE_PRIVATE : null
-    },
-
-    isBuiltin(collection) {
-      return !!BUILTINS[collection]
-    },
-
-    /**
-     * Does Collection.put follow the add/set merge path for this collection?
-     *
-     * - User-defined: always yes. Non-local user collections get auto-generated
-     *   `add-${type}` dispatches; local collections take the merge path even
-     *   without dispatches (they write straight to the local store).
-     * - Built-ins: derived from cero's actual dispatch table — `false` for
-     *   collections cero exposes only via `set-${type}` (e.g. profile, settings).
-     */
-    hasAdd(collection) {
-      const builtin = BUILTINS[collection]
-      if (builtin) return ceroHasAdd(builtin.scope, builtin.type)
-      return !!collections[collection]
-    },
-
-    keysOf(collection) {
-      if (BUILTINS[collection]) return BUILTINS[collection].key
-      return collections[collection]?.key || ['id']
-    },
-
-    isLocalBuiltin(collection) {
-      return !!LOCAL_BUILTINS[collection]
-    },
-
-    /**
-     * Resolve a name to its local-scope type. Returns null if the name doesn't
-     * map to a local collection (cero built-in or user-declared `scope: 'local'`).
-     */
-    localTypeOf(collection) {
-      if (LOCAL_BUILTINS[collection]) return LOCAL_BUILTINS[collection].type
-      const def = collections[collection]
-      if (def?.scope === SCOPE_LOCAL) return singular(collection)
-      return null
-    },
-
-    localKeysOf(collection) {
-      if (LOCAL_BUILTINS[collection]) return LOCAL_BUILTINS[collection].key
-      const def = collections[collection]
-      if (def?.scope === SCOPE_LOCAL) return def.key || ['id']
-      return null
-    },
-
-    /**
-     * Resolve a local collection name to its hyperdb spec + path. Returns null
-     * if `name` isn't a local collection. Local built-ins don't have input-X
-     * types, so the prefix is ignored for them.
-     */
-    localResolve(collection, prefix) {
-      const ns = scopeNs(SCOPE_LOCAL)
-      if (LOCAL_BUILTINS[collection]) {
-        return { spec: ns, path: `@${ns}/${LOCAL_BUILTINS[collection].type}` }
-      }
-      const def = collections[collection]
-      if (def?.scope === SCOPE_LOCAL) {
-        const type = singular(collection)
-        const name = prefix ? `${prefix}-${type}` : type
-        return { spec: ns, path: `@${ns}/${name}` }
-      }
-      return null
-    },
-
-    isLocal(collection) {
-      return isLocal(this.getScope(collection))
-    },
-    isPrivate(collection) {
-      return isPrivate(this.getScope(collection))
-    },
-    isShared(collection) {
-      return isShared(this.getScope(collection))
-    },
-
-    hasTimestamps(collection) {
-      return collections[collection]?.timestamps === true
-    },
-
-    hasCounter(collection) {
-      return collections[collection]?.counter === true
-    },
-
-    counterNames(scope) {
-      const items =
-        scope === SCOPE_SHARED
-          ? sharedEntries
-          : scope === SCOPE_LOCAL
-            ? localEntries
-            : privateEntries
-      // map: type name (singular) → collection name (plural)
-      const map = {}
-      for (const [name, def] of items) {
-        if (def.counter) map[types.get(name)] = name
-      }
-      return map
-    },
-
-    resolve(collection, prefix) {
-      const scope = this.getScope(collection)
-      const type = types.get(collection)
-      const name = prefix ? `${prefix}-${type}` : type
-      return { spec: scopeNs(scope), path: `@${nsFor(scope)}/${name}` }
-    },
-
-    require(collection, context) {
-      const scope = this.getScope(collection)
-      if (!scope) throw new Error(`Unknown collection: '${collection}'`)
-      if (context === 'db' && scope === SCOPE_SHARED) {
-        throw new Error(`'${collection}' is shared — use room.collection('${collection}')`)
-      }
-      if (context === 'room' && scope !== SCOPE_SHARED) {
-        throw new Error(`'${collection}' is ${scope} — use db.collection('${collection}')`)
-      }
-      return scope
-    },
-
-    getPath(collection) {
-      const scope = this.getScope(collection)
-      return `@${nsFor(scope)}/${collection}`
-    },
-
-    build(scope, register, nsName) {
-      const items =
-        scope === SCOPE_SHARED
-          ? sharedEntries
-          : scope === SCOPE_LOCAL
-            ? localEntries
-            : privateEntries
-      const local = scope === SCOPE_LOCAL
-      const ns = nsName || scopeNs(scope)
-      for (const [name, def] of items) {
-        if (BUILTINS[name]) {
-          // Built-in extension: re-register the type with extra fields appended.
-          // cero's later registration is idempotent and skips when the type already exists.
-          const typeName = BUILTINS[name].type
-          const baseFields = baseFieldsOf(scope, ns, typeName)
-          const userFields = toFields(def.fields || {}).map((f) => ({ ...f, required: false }))
-
-          const baseNames = new Set(baseFields.map((f) => f.name))
-          for (const uf of userFields) {
-            if (baseNames.has(uf.name)) {
-              throw new Error(
-                `'${uf.name}' is a base field of '${typeName}' and cannot be redeclared`
-              )
-            }
-          }
-
-          const allFields = [...baseFields, ...userFields]
-          register.type({ name: typeName, compact: false, fields: allFields })
-          register.type({
-            name: `input-${typeName}`,
-            compact: false,
-            fields: allFields.map((f) => ({ ...f, required: false }))
-          })
-
-          if (def.indexes) {
-            for (const [idx, idxFields] of Object.entries(def.indexes)) {
-              register.index({
-                name: `${name}-${idx}`,
-                collection: `@${ns}/${name}`,
-                key: idxFields
-              })
-            }
-          }
-
-          // Register custom dispatches for user-supplied handlers.
-          // Use input-${type} (all-optional fields) so callers can pass partial
-          // payloads like { id } without re-supplying every base field.
-          if (def.handlers) {
-            for (const op of Object.keys(def.handlers)) {
-              register.dispatch({ name: op, requestType: `@${ns}/input-${typeName}` })
-            }
-          }
-          continue
-        }
-
-        const type = types.get(name)
-        const fields = schemaFields(def)
-        const typePath = `@${ns}/${type}`
-
-        register.type({ name: type, compact: false, fields })
-        register.type({ name: `input-${type}`, compact: false, fields: inputFields(def) })
-        if (!local) register.type({ name: `del-${type}`, compact: false, fields: delFields(def) })
-
-        register.collection({
-          name,
-          schema: typePath,
-          key: def.key || ['id'],
-          counter: !!def.counter
-        })
-
-        if (def.indexes) {
-          for (const [idx, idxFields] of Object.entries(def.indexes)) {
-            register.index({ name: `${name}-${idx}`, collection: `@${ns}/${name}`, key: idxFields })
-          }
-        }
-
-        if (!local) {
-          register.dispatch({ name: `add-${type}`, requestType: typePath })
-          register.dispatch({ name: `set-${type}`, requestType: typePath })
-          register.dispatch({ name: `del-${type}`, requestType: `@${ns}/del-${type}` })
-        }
-
-        // Register custom dispatches for user-supplied handlers.
-        // Use input-${type} so callers can pass partial payloads.
-        if (!local && def.handlers) {
-          for (const op of Object.keys(def.handlers)) {
-            register.dispatch({ name: op, requestType: `@${ns}/input-${type}` })
-          }
-        }
-      }
-
-      // Register input-${type} for implicit built-ins (not in user schema)
-      // so the RPC bridge can encode partial payloads for Collection writes.
-      if (!local) {
-        for (const [name, info] of Object.entries(BUILTINS)) {
-          if (info.scope !== scope) continue
-          if (collections[name]) continue // already handled by built-in branch above
-          const baseFields = baseFieldsOf(info.scope, ns, info.type)
-          register.type({
-            name: `input-${info.type}`,
-            compact: false,
-            fields: baseFields.map((f) => ({ ...f, required: false }))
-          })
-        }
-      }
-    },
-
-    routes(scope) {
-      const items = scope === SCOPE_PRIVATE ? privateEntries : sharedEntries
-      const handlers = {}
-      const p = (name) => `@${nsFor(scope)}/${name}`
-      for (const [name, def] of items) {
-        if (BUILTINS[name]) {
-          // Built-in extension: cero already owns add/set/del — only register custom handlers.
-          if (def.handlers) {
-            for (const [op, handler] of Object.entries(def.handlers)) {
-              handlers[p(op)] = handler
-            }
-          }
-          continue
-        }
-
-        const type = types.get(name)
-        const path = p(name)
-        const keys = def.key || ['id']
-
-        handlers[p(`add-${type}`)] = async (op, ctx) => {
-          const counterPath = p('counters')
-          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
-          op.index = counter.value
-          counter.value++
-          await ctx.view.insert(counterPath, counter)
-          await ctx.view.insert(path, op)
-        }
-
-        handlers[p(`set-${type}`)] = (op, ctx) => ctx.view.insert(path, op)
-        handlers[p(`del-${type}`)] = async (op, ctx) => {
-          await ctx.view.delete(
-            path,
-            keys.reduce((acc, k) => ((acc[k] = op[k]), acc), {})
-          )
-          const counterPath = p('counters')
-          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
-          counter.value = Math.max(0, counter.value - 1)
-          await ctx.view.insert(counterPath, counter)
-        }
-
-        if (def.handlers) {
-          for (const [op, handler] of Object.entries(def.handlers)) {
-            handlers[p(op)] = handler
-          }
-        }
-      }
-
-      return handlers
-    }
-  }
+/**
+ * Wrap a definitions object so the builder can recognise it as a schema.
+ *
+ * @param {SchemaDefs} defs
+ * @returns {Schema}
+ */
+export function schema(defs) {
+  if (!defs || typeof defs !== 'object') throw CeroError.INVALID('schema(defs) must be an object')
+  return { defs }
 }