@rocicorp/zero 0.3.2024102300 → 0.3.2024102500

package/out/react.js

@@ -141,7 +141,6 @@ var ViewWrapper = class {
     }
     this.#view = this.#query.materialize();
     this.#view.addListener(this.#onData);
-    this.#view.hydrate();
     this.#onMaterialized(this);
   };
   getSnapshot = () => this.#snapshot;

package/out/react.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../zero-react/src/use-query.tsx", "../../shared/src/deep-clone.ts", "../../zero-react/src/use-zero.tsx"],
-  "sourcesContent": ["import {useSyncExternalStore} from 'react';\nimport {deepClone} from '../../shared/src/deep-clone.js';\nimport type {\n  Query,\n  QueryImpl,\n  QueryType,\n  Smash,\n  TableSchema,\n  TypedView,\n} from '../../zero-client/src/mod.js';\nimport type {Immutable} from '../../shared/src/immutable.js';\nimport {useZero} from './use-zero.js';\n\nexport function useQuery<\n  TSchema extends TableSchema,\n  TReturn extends QueryType,\n>(q: Query<TSchema, TReturn>, enable: boolean = true): Smash<TReturn> {\n  const z = useZero();\n  const view = viewStore.getView(\n    z.clientID,\n    q as QueryImpl<TSchema, TReturn>,\n    enable,\n  );\n  // https://react.dev/reference/react/useSyncExternalStore\n  return useSyncExternalStore(view.subscribeReactInternals, view.getSnapshot);\n}\n\nconst emptyArray: unknown[] = [];\nconst disabledSubscriber = () => () => {};\n\n/**\n * A global store of all active views.\n *\n * React subscribes and unsubscribes to these views\n * via `useSyncExternalStore`.\n *\n * Managing views through `useEffect` or `useLayoutEffect` causes\n * inconsistencies because effects run after render.\n *\n * For example, if useQuery used use*Effect in the component below:\n * ```ts\n * function Foo({issueID}) {\n *   const issue = useQuery(z.query.issue.where('id', issueID).one());\n *   if (issue?.id !== undefined && issue.id !== issueID) {\n *     console.log('MISMATCH!', issue.id, issueID);\n *   }\n * }\n * ```\n *\n * `MISMATCH` will be printed whenever the `issueID` prop changes.\n *\n * This is because the component will render once with\n * the old state returned from `useQuery`. Then the effect inside\n * `useQuery` will run. The component will render again with the new\n * state. This inconsistent transition can cause unexpected results.\n *\n * Emulating `useEffect` via `useState` and `if` causes resource leaks.\n * That is:\n *\n * ```ts\n * function useQuery(q) {\n *   const [oldHash, setOldHash] = useState();\n *   if (hash(q) !== oldHash) {\n *      // make new view\n *   }\n *\n *   useEffect(() => {\n *     return () => view.destroy();\n *   }, []);\n * }\n * ```\n *\n * I'm not sure why but in strict mode the cleanup function\n * fails to be called for the first instance of the view and only\n * cleans up later instances.\n *\n * Swapping `useState` to `useRef` has similar problems.\n */\nclass ViewStore {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  #views = new Map<string, ViewWrapper<any, any>>();\n\n  getView<TSchema extends TableSchema, TReturn extends QueryType>(\n    clientID: string,\n    query: QueryImpl<TSchema, TReturn>,\n    enabled: boolean,\n  ): {\n    getSnapshot: () => Smash<TReturn>;\n    subscribeReactInternals: (internals: () => void) => () => void;\n  } {\n    if (!enabled) {\n      return {\n        getSnapshot: () =>\n          (query.singular ? undefined : emptyArray) as Smash<TReturn>,\n        subscribeReactInternals: disabledSubscriber,\n      };\n    }\n\n    const hash = JSON.stringify(query.ast) + clientID;\n    let existing = this.#views.get(hash);\n    if (!existing) {\n      existing = new ViewWrapper(\n        query,\n        view => {\n          const lastView = this.#views.get(hash);\n          // I don't think this can happen\n          // but lets guard against it so we don't\n          // leak resources.\n          if (lastView && lastView !== view) {\n            throw new Error('View already exists');\n          }\n          this.#views.set(hash, view);\n        },\n        () => {\n          this.#views.delete(hash);\n        },\n      ) as ViewWrapper<TSchema, TReturn>;\n      this.#views.set(hash, existing);\n    }\n    return existing;\n  }\n}\n\nconst viewStore = new ViewStore();\n\n/**\n * This wraps and ref counts a view.\n *\n * The only signal we have from React as to whether or not it is\n * done with a view is when it calls `unsubscribe`.\n *\n * In non-strict-mode we can clean up the view as soon\n * as the listener count goes to 0.\n *\n * In strict-mode, the listener cound will go to 0 then a\n * new listener for the same view is immeidatiely added back.\n *\n * This is why the `onMaterialized` and `onDematerialized` callbacks exist --\n * they allow a view which React is still referencing to be added\n * back into the store when React re-subscribes to it.\n *\n * This wrapper also exists to deal with the various\n * `useSyncExternalStore` caveats that cause excessive\n * re-renders and materializations.\n *\n * See: https://react.dev/reference/react/useSyncExternalStore#caveats\n * Especially:\n * 1. The store snapshot returned by getSnapshot must be immutable. If the underlying store has mutable data, return a new immutable snapshot if the data has changed. Otherwise, return a cached last snapshot.\n * 2. If a different subscribe function is passed during a re-render, React will re-subscribe to the store using the newly passed subscribe function. You can prevent this by declaring subscribe outside the component.\n */\nclass ViewWrapper<TSchema extends TableSchema, TReturn extends QueryType> {\n  #view: TypedView<Smash<TReturn>> | undefined;\n  readonly #defaultSnapshot: Smash<TReturn>;\n  readonly #onDematerialized;\n  readonly #onMaterialized;\n  readonly #query: QueryImpl<TSchema, TReturn>;\n  #snapshot: Smash<TReturn>;\n  #reactInternals: Set<() => void>;\n\n  constructor(\n    query: QueryImpl<TSchema, TReturn>,\n    onMaterialized: (view: ViewWrapper<TSchema, TReturn>) => void,\n    onDematerialized: () => void,\n  ) {\n    this.#defaultSnapshot = (query.singular\n      ? undefined\n      : emptyArray) as unknown as Smash<TReturn>;\n    this.#snapshot = this.#defaultSnapshot;\n    this.#onMaterialized = onMaterialized;\n    this.#onDematerialized = onDematerialized;\n    this.#reactInternals = new Set();\n    this.#query = query;\n  }\n\n  #onData = (snap: Immutable<Smash<TReturn>>) => {\n    this.#snapshot = (\n      snap === undefined ? snap : deepClone(snap)\n    ) as Smash<TReturn>;\n    for (const internals of this.#reactInternals) {\n      internals();\n    }\n  };\n\n  #materializeIfNeeded = () => {\n    if (this.#view) {\n      return;\n    }\n\n    this.#view = this.#query.materialize();\n    this.#view.addListener(this.#onData);\n    this.#view.hydrate();\n\n    this.#onMaterialized(this);\n  };\n\n  getSnapshot = () => this.#snapshot;\n\n  subscribeReactInternals = (internals: () => void): (() => void) => {\n    this.#reactInternals.add(internals);\n    this.#materializeIfNeeded();\n    return () => {\n      this.#reactInternals.delete(internals);\n      if (this.#reactInternals.size === 0) {\n        this.#view?.destroy();\n        this.#view = undefined;\n        this.#onDematerialized();\n      }\n    };\n  };\n}\n", "import {hasOwn} from './has-own.js';\nimport type {JSONValue, ReadonlyJSONValue} from './json.js';\n\nexport function deepClone(value: ReadonlyJSONValue): JSONValue {\n  const seen: Array<ReadonlyJSONValue> = [];\n  return internalDeepClone(value, seen);\n}\n\nexport function internalDeepClone(\n  value: ReadonlyJSONValue,\n  seen: Array<ReadonlyJSONValue>,\n): JSONValue {\n  switch (typeof value) {\n    case 'boolean':\n    case 'number':\n    case 'string':\n    case 'undefined':\n      return value;\n    case 'object': {\n      if (value === null) {\n        return null;\n      }\n      if (seen.includes(value)) {\n        throw new Error('Cyclic object');\n      }\n      seen.push(value);\n      if (Array.isArray(value)) {\n        const rv = value.map(v => internalDeepClone(v, seen));\n        seen.pop();\n        return rv;\n      }\n\n      const obj: JSONValue = {};\n\n      for (const k in value) {\n        if (hasOwn(value, k)) {\n          const v = (value as Record<string, ReadonlyJSONValue>)[k];\n          if (v !== undefined) {\n            obj[k] = internalDeepClone(v, seen);\n          }\n        }\n      }\n      seen.pop();\n      return obj;\n    }\n\n    default:\n      throw new Error(`Invalid type: ${typeof value}`);\n  }\n}\n", "import {createContext, useContext} from 'react';\nimport type {Schema, Zero} from '../../zero-client/src/mod.js';\n\n// eslint-disable-next-line @typescript-eslint/naming-convention\nconst ZeroContext = createContext<Zero<Schema> | undefined>(undefined);\n\nexport function useZero<S extends Schema>(): Zero<S> {\n  const zero = useContext(ZeroContext);\n  if (zero === undefined) {\n    throw new Error('useZero must be used within a ZeroProvider');\n  }\n  return zero as Zero<S>;\n}\n\nexport function createUseZero<S extends Schema>() {\n  return () => useZero<S>();\n}\n\nexport function ZeroProvider<S extends Schema>({\n  children,\n  zero,\n}: {\n  children: React.ReactNode;\n  zero: Zero<S>;\n}) {\n  return (\n    <ZeroContext.Provider value={zero as Zero<Schema>}>\n      {children}\n    </ZeroContext.Provider>\n  );\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import {useSyncExternalStore} from 'react';\nimport {deepClone} from '../../shared/src/deep-clone.js';\nimport type {Immutable} from '../../shared/src/immutable.js';\nimport type {\n  Query,\n  QueryImpl,\n  QueryType,\n  Smash,\n  TableSchema,\n  TypedView,\n} from '../../zero-client/src/mod.js';\nimport {useZero} from './use-zero.js';\n\nexport function useQuery<\n  TSchema extends TableSchema,\n  TReturn extends QueryType,\n>(q: Query<TSchema, TReturn>, enable: boolean = true): Smash<TReturn> {\n  const z = useZero();\n  const view = viewStore.getView(\n    z.clientID,\n    q as QueryImpl<TSchema, TReturn>,\n    enable,\n  );\n  // https://react.dev/reference/react/useSyncExternalStore\n  return useSyncExternalStore(view.subscribeReactInternals, view.getSnapshot);\n}\n\nconst emptyArray: unknown[] = [];\nconst disabledSubscriber = () => () => {};\n\n/**\n * A global store of all active views.\n *\n * React subscribes and unsubscribes to these views\n * via `useSyncExternalStore`.\n *\n * Managing views through `useEffect` or `useLayoutEffect` causes\n * inconsistencies because effects run after render.\n *\n * For example, if useQuery used use*Effect in the component below:\n * ```ts\n * function Foo({issueID}) {\n *   const issue = useQuery(z.query.issue.where('id', issueID).one());\n *   if (issue?.id !== undefined && issue.id !== issueID) {\n *     console.log('MISMATCH!', issue.id, issueID);\n *   }\n * }\n * ```\n *\n * `MISMATCH` will be printed whenever the `issueID` prop changes.\n *\n * This is because the component will render once with\n * the old state returned from `useQuery`. Then the effect inside\n * `useQuery` will run. The component will render again with the new\n * state. This inconsistent transition can cause unexpected results.\n *\n * Emulating `useEffect` via `useState` and `if` causes resource leaks.\n * That is:\n *\n * ```ts\n * function useQuery(q) {\n *   const [oldHash, setOldHash] = useState();\n *   if (hash(q) !== oldHash) {\n *      // make new view\n *   }\n *\n *   useEffect(() => {\n *     return () => view.destroy();\n *   }, []);\n * }\n * ```\n *\n * I'm not sure why but in strict mode the cleanup function\n * fails to be called for the first instance of the view and only\n * cleans up later instances.\n *\n * Swapping `useState` to `useRef` has similar problems.\n */\nclass ViewStore {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  #views = new Map<string, ViewWrapper<any, any>>();\n\n  getView<TSchema extends TableSchema, TReturn extends QueryType>(\n    clientID: string,\n    query: QueryImpl<TSchema, TReturn>,\n    enabled: boolean,\n  ): {\n    getSnapshot: () => Smash<TReturn>;\n    subscribeReactInternals: (internals: () => void) => () => void;\n  } {\n    if (!enabled) {\n      return {\n        getSnapshot: () =>\n          (query.singular ? undefined : emptyArray) as Smash<TReturn>,\n        subscribeReactInternals: disabledSubscriber,\n      };\n    }\n\n    const hash = JSON.stringify(query.ast) + clientID;\n    let existing = this.#views.get(hash);\n    if (!existing) {\n      existing = new ViewWrapper(\n        query,\n        view => {\n          const lastView = this.#views.get(hash);\n          // I don't think this can happen\n          // but lets guard against it so we don't\n          // leak resources.\n          if (lastView && lastView !== view) {\n            throw new Error('View already exists');\n          }\n          this.#views.set(hash, view);\n        },\n        () => {\n          this.#views.delete(hash);\n        },\n      ) as ViewWrapper<TSchema, TReturn>;\n      this.#views.set(hash, existing);\n    }\n    return existing;\n  }\n}\n\nconst viewStore = new ViewStore();\n\n/**\n * This wraps and ref counts a view.\n *\n * The only signal we have from React as to whether or not it is\n * done with a view is when it calls `unsubscribe`.\n *\n * In non-strict-mode we can clean up the view as soon\n * as the listener count goes to 0.\n *\n * In strict-mode, the listener cound will go to 0 then a\n * new listener for the same view is immeidatiely added back.\n *\n * This is why the `onMaterialized` and `onDematerialized` callbacks exist --\n * they allow a view which React is still referencing to be added\n * back into the store when React re-subscribes to it.\n *\n * This wrapper also exists to deal with the various\n * `useSyncExternalStore` caveats that cause excessive\n * re-renders and materializations.\n *\n * See: https://react.dev/reference/react/useSyncExternalStore#caveats\n * Especially:\n * 1. The store snapshot returned by getSnapshot must be immutable. If the underlying store has mutable data, return a new immutable snapshot if the data has changed. Otherwise, return a cached last snapshot.\n * 2. If a different subscribe function is passed during a re-render, React will re-subscribe to the store using the newly passed subscribe function. You can prevent this by declaring subscribe outside the component.\n */\nclass ViewWrapper<TSchema extends TableSchema, TReturn extends QueryType> {\n  #view: TypedView<Smash<TReturn>> | undefined;\n  readonly #defaultSnapshot: Smash<TReturn>;\n  readonly #onDematerialized;\n  readonly #onMaterialized;\n  readonly #query: QueryImpl<TSchema, TReturn>;\n  #snapshot: Smash<TReturn>;\n  #reactInternals: Set<() => void>;\n\n  constructor(\n    query: QueryImpl<TSchema, TReturn>,\n    onMaterialized: (view: ViewWrapper<TSchema, TReturn>) => void,\n    onDematerialized: () => void,\n  ) {\n    this.#defaultSnapshot = (query.singular\n      ? undefined\n      : emptyArray) as unknown as Smash<TReturn>;\n    this.#snapshot = this.#defaultSnapshot;\n    this.#onMaterialized = onMaterialized;\n    this.#onDematerialized = onDematerialized;\n    this.#reactInternals = new Set();\n    this.#query = query;\n  }\n\n  #onData = (snap: Immutable<Smash<TReturn>>) => {\n    this.#snapshot = (\n      snap === undefined ? snap : deepClone(snap)\n    ) as Smash<TReturn>;\n    for (const internals of this.#reactInternals) {\n      internals();\n    }\n  };\n\n  #materializeIfNeeded = () => {\n    if (this.#view) {\n      return;\n    }\n\n    this.#view = this.#query.materialize();\n    this.#view.addListener(this.#onData);\n\n    this.#onMaterialized(this);\n  };\n\n  getSnapshot = () => this.#snapshot;\n\n  subscribeReactInternals = (internals: () => void): (() => void) => {\n    this.#reactInternals.add(internals);\n    this.#materializeIfNeeded();\n    return () => {\n      this.#reactInternals.delete(internals);\n      if (this.#reactInternals.size === 0) {\n        this.#view?.destroy();\n        this.#view = undefined;\n        this.#onDematerialized();\n      }\n    };\n  };\n}\n", "import {hasOwn} from './has-own.js';\nimport type {JSONValue, ReadonlyJSONValue} from './json.js';\n\nexport function deepClone(value: ReadonlyJSONValue): JSONValue {\n  const seen: Array<ReadonlyJSONValue> = [];\n  return internalDeepClone(value, seen);\n}\n\nexport function internalDeepClone(\n  value: ReadonlyJSONValue,\n  seen: Array<ReadonlyJSONValue>,\n): JSONValue {\n  switch (typeof value) {\n    case 'boolean':\n    case 'number':\n    case 'string':\n    case 'undefined':\n      return value;\n    case 'object': {\n      if (value === null) {\n        return null;\n      }\n      if (seen.includes(value)) {\n        throw new Error('Cyclic object');\n      }\n      seen.push(value);\n      if (Array.isArray(value)) {\n        const rv = value.map(v => internalDeepClone(v, seen));\n        seen.pop();\n        return rv;\n      }\n\n      const obj: JSONValue = {};\n\n      for (const k in value) {\n        if (hasOwn(value, k)) {\n          const v = (value as Record<string, ReadonlyJSONValue>)[k];\n          if (v !== undefined) {\n            obj[k] = internalDeepClone(v, seen);\n          }\n        }\n      }\n      seen.pop();\n      return obj;\n    }\n\n    default:\n      throw new Error(`Invalid type: ${typeof value}`);\n  }\n}\n", "import {createContext, useContext} from 'react';\nimport type {Schema, Zero} from '../../zero-client/src/mod.js';\n\n// eslint-disable-next-line @typescript-eslint/naming-convention\nconst ZeroContext = createContext<Zero<Schema> | undefined>(undefined);\n\nexport function useZero<S extends Schema>(): Zero<S> {\n  const zero = useContext(ZeroContext);\n  if (zero === undefined) {\n    throw new Error('useZero must be used within a ZeroProvider');\n  }\n  return zero as Zero<S>;\n}\n\nexport function createUseZero<S extends Schema>() {\n  return () => useZero<S>();\n}\n\nexport function ZeroProvider<S extends Schema>({\n  children,\n  zero,\n}: {\n  children: React.ReactNode;\n  zero: Zero<S>;\n}) {\n  return (\n    <ZeroContext.Provider value={zero as Zero<Schema>}>\n      {children}\n    </ZeroContext.Provider>\n  );\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/out/zero-cache/src/db/create.js

@@ -34,6 +34,6 @@ export function createIndexStatement(index) {
         .map(([name, dir]) => `${id(name)} ${dir}`)
         .join(',');
     const unique = index.unique ? 'UNIQUE' : '';
-    return `CREATE ${unique} INDEX ${id(index.name)} ON ${id(index.tableName)} (${columns})`;
+    return `CREATE ${unique} INDEX ${id(index.name)} ON ${id(index.tableName)} (${columns});`;
 }
 //# sourceMappingURL=create.js.map

package/out/zero-cache/src/db/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,iBAAiB,CAAC;AAQ3C,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA+B;IAClE,qEAAqE;IACrE,uEAAuE;IACvE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;SACtC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAC,GAAG,EAAE,CAAC,EAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAC,GAAG,EAAE,CAAC,EAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SAC/C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,EAAC,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAC,CAAC,EAAE,CAAC,CAAC;IAC5E,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,UAAU,GACd,QAAQ,IAAI,IAAI;QACd,CAAC,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACtD,CAAC,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAoB;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;SAC1C,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5C,OAAO,UAAU,MAAM,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CACtD,KAAK,CAAC,SAAS,CAChB,KAAK,OAAO,GAAG,CAAC;AACnB,CAAC"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,iBAAiB,CAAC;AAQ3C,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA+B;IAClE,qEAAqE;IACrE,uEAAuE;IACvE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;SACtC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAC,GAAG,EAAE,CAAC,EAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAC,GAAG,EAAE,CAAC,EAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SAC/C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,EAAC,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAC,CAAC,EAAE,CAAC,CAAC;IAC5E,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,UAAU,GACd,QAAQ,IAAI,IAAI;QACd,CAAC,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACtD,CAAC,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAoB;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;SAC1C,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5C,OAAO,UAAU,MAAM,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CACtD,KAAK,CAAC,SAAS,CAChB,KAAK,OAAO,IAAI,CAAC;AACpB,CAAC"}

package/out/zero-cache/src/db/migration-lite.d.ts

@@ -0,0 +1,78 @@
+import type { LogContext } from '@rocicorp/logger';
+import * as v from '../../../shared/src/valita.js';
+import type { Database as Db } from '../../../zqlite/src/db.js';
+type Operations = (log: LogContext, tx: Db) => Promise<void> | void;
+/**
+ * Encapsulates the logic for setting up or upgrading to a new schema. After the
+ * Migration code successfully completes, {@link runSchemaMigrations}
+ * will update the schema version and commit the transaction.
+ */
+export type Migration = {
+    /**
+     * Perform database operations that create or alter table structure. This is
+     * called at most once during lifetime of the application. If a `migrateData()`
+     * operation is defined, that will be performed after `migrateSchema()` succeeds.
+     */
+    migrateSchema?: Operations;
+    /**
+     * Perform database operations to migrate data to the new schema. This is
+     * called after `migrateSchema()` (if defined), and may be called again
+     * to re-migrate data after the server was rolled back to an earlier version,
+     * and rolled forward again.
+     *
+     * Consequently, the logic in `migrateData()` must be idempotent.
+     */
+    migrateData?: Operations;
+    /**
+     * Sets the `minSafeVersion` to the specified value, prohibiting running
+     * any earlier code versions.
+     */
+    minSafeVersion?: number;
+};
+/**
+ * Mapping of incremental migrations to move from the previous old code
+ * version to next one. Versions must be non-zero.
+ *
+ * The schema resulting from performing incremental migrations should be
+ * equivalent to that of the `setupMigration` on a blank database.
+ *
+ * The highest destinationVersion of this map denotes the current
+ * "code version", and is also used as the destination version when
+ * running the initial setup migration on a blank database.
+ */
+export type IncrementalMigrationMap = {
+    [destinationVersion: number]: Migration;
+};
+/**
+ * Ensures that the schema is compatible with the current code, updating and
+ * migrating the schema if necessary.
+ */
+export declare function runSchemaMigrations(log: LogContext, debugName: string, dbPath: string, setupMigration: Migration, incrementalMigrationMap: IncrementalMigrationMap): Promise<void>;
+export declare const versionHistory: v.ObjectType<{
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.Type<number>;
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.Type<number>;
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.Type<number>;
+}, undefined>;
+export type VersionHistory = v.Infer<typeof versionHistory>;
+export declare function getVersionHistory(db: Db): VersionHistory;
+export {};
+//# sourceMappingURL=migration-lite.d.ts.map

package/out/zero-cache/src/db/migration-lite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-lite.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,KAAK,EAAC,QAAQ,IAAI,EAAE,EAAC,MAAM,2BAA2B,CAAC;AAG9D,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CAoFf;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,EAAE,GAAG,cAAc,CAmBxD"}

package/out/zero-cache/src/db/migration-lite.js

@@ -0,0 +1,181 @@
+import { assert } from '../../../shared/src/asserts.js';
+import { randInt } from '../../../shared/src/rand.js';
+import * as v from '../../../shared/src/valita.js';
+import { Database } from '../../../zqlite/src/db.js';
+/**
+ * Ensures that the schema is compatible with the current code, updating and
+ * migrating the schema if necessary.
+ */
+export async function runSchemaMigrations(log, debugName, dbPath, setupMigration, incrementalMigrationMap) {
+    log = log.withContext('initSchema', randInt(0, Number.MAX_SAFE_INTEGER).toString(36));
+    const db = new Database(log, dbPath);
+    db.pragma('foreign_keys = OFF');
+    try {
+        const versionMigrations = sorted(incrementalMigrationMap);
+        assert(versionMigrations.length, `Must specify a at least one version migration`);
+        assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
+        const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
+        let versions = await runTransaction(log, db, tx => {
+            const versions = getVersionHistory(tx);
+            if (codeVersion < versions.minSafeVersion) {
+                throw new Error(`Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`);
+            }
+            if (versions.dataVersion > codeVersion) {
+                log.info?.(`Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`);
+                return updateVersionHistory(log, tx, versions, codeVersion);
+            }
+            return versions;
+        });
+        if (versions.dataVersion < codeVersion) {
+            const migrations = versions.dataVersion === 0
+                ? // For the empty database v0, only run the setup migration.
+                    [[codeVersion, setupMigration]]
+                : versionMigrations;
+            for (const [dest, migration] of migrations) {
+                if (versions.dataVersion < dest) {
+                    log.info?.(`Migrating schema from v${versions.dataVersion} to v${dest}`);
+                    void log.flush(); // Flush logs before each migration to help debug crash-y migrations.
+                    db.pragma('synchronous = OFF'); // For schema migrations we'll wait for the disk flush after the migration.
+                    versions = await runTransaction(log, db, async (tx) => {
+                        // Fetch meta from within the transaction to make the migration atomic.
+                        let versions = getVersionHistory(tx);
+                        if (versions.dataVersion < dest) {
+                            versions = await runMigration(log, tx, versions, dest, migration);
+                            assert(versions.dataVersion === dest);
+                        }
+                        return versions;
+                    });
+                    db.pragma('synchronous = NORMAL');
+                    db.exec('VACUUM');
+                    log.info?.('VACUUM completed');
+                    db.exec('ANALYZE main');
+                    log.info?.('ANALYZE completed');
+                }
+            }
+        }
+        assert(versions.dataVersion === codeVersion);
+        log.info?.(`Running ${debugName} at schema v${codeVersion}`);
+    }
+    catch (e) {
+        log.error?.('Error in ensureSchemaMigrated', e);
+        throw e;
+    }
+    finally {
+        db.close();
+        void log.flush(); // Flush the logs but do not block server progress on it.
+    }
+}
+function sorted(incrementalMigrationMap) {
+    const versionMigrations = [];
+    for (const [v, m] of Object.entries(incrementalMigrationMap)) {
+        versionMigrations.push([Number(v), m]);
+    }
+    return versionMigrations.sort(([a], [b]) => a - b);
+}
+// Exposed for tests.
+export const versionHistory = v.object({
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.number(),
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.number(),
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.number(),
+});
+// Exposed for tests
+export function getVersionHistory(db) {
+    // Note: The `lock` column transparently ensures that at most one row exists.
+    db.prepare(`
+    CREATE TABLE IF NOT EXISTS "_zero.versionHistory" (
+      dataVersion INTEGER NOT NULL,
+      schemaVersion INTEGER NOT NULL,
+      minSafeVersion INTEGER NOT NULL,
+
+      lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)
+    );
+  `).run();
+    const result = db
+        .prepare('SELECT dataVersion, schemaVersion, minSafeVersion FROM "_zero.versionHistory"')
+        .get();
+    return result ?? { dataVersion: 0, schemaVersion: 0, minSafeVersion: 0 };
+}
+function updateVersionHistory(log, db, prev, newVersion, minSafeVersion) {
+    assert(newVersion > 0);
+    const meta = {
+        ...prev,
+        dataVersion: newVersion,
+        // The schemaVersion never moves backwards.
+        schemaVersion: Math.max(newVersion, prev.schemaVersion),
+        minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),
+    };
+    db.prepare(`
+    INSERT INTO "_zero.versionHistory" (dataVersion, schemaVersion, minSafeVersion, lock)
+    VALUES (@dataVersion, @schemaVersion, @minSafeVersion, 1)
+    ON CONFLICT (lock) DO UPDATE
+    SET dataVersion=@dataVersion,
+        schemaVersion=@schemaVersion,
+        minSafeVersion=@minSafeVersion
+  `).run(meta);
+    return meta;
+}
+async function runMigration(log, tx, versions, destinationVersion, migration) {
+    if (versions.schemaVersion < destinationVersion) {
+        await migration.migrateSchema?.(log, tx);
+    }
+    if (versions.dataVersion < destinationVersion) {
+        await migration.migrateData?.(log, tx);
+    }
+    return updateVersionHistory(log, tx, versions, destinationVersion, migration.minSafeVersion);
+}
+/**
+ * Bumps the rollback limit [[toAtLeast]] the specified version.
+ * Leaves the rollback limit unchanged if it is equal or greater.
+ */
+function getMinSafeVersion(log, current, proposedSafeVersion) {
+    if (proposedSafeVersion === undefined) {
+        return current.minSafeVersion;
+    }
+    // Sanity check to maintain the invariant that running code is never
+    // earlier than the rollback limit.
+    assert(proposedSafeVersion <= current.dataVersion + 1);
+    if (current.minSafeVersion >= proposedSafeVersion) {
+        // The rollback limit must never move backwards.
+        log.debug?.(`rollback limit is already at ${current.minSafeVersion}, ` +
+            `don't need to bump to ${proposedSafeVersion}`);
+        return current.minSafeVersion;
+    }
+    log.info?.(`bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`);
+    return proposedSafeVersion;
+}
+// Note: We use a custom transaction wrapper (instead of db.begin(...)) in order
+// to support async operations within the transaction.
+async function runTransaction(log, db, tx) {
+    db.prepare('BEGIN EXCLUSIVE').run();
+    try {
+        const result = await tx(db);
+        db.prepare('COMMIT').run();
+        return result;
+    }
+    catch (e) {
+        db.prepare('ROLLBACK').run();
+        log.error?.('Aborted transaction due to error', e);
+        throw e;
+    }
+}
+//# sourceMappingURL=migration-lite.js.map

package/out/zero-cache/src/db/migration-lite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-lite.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/db/migration.d.ts

@@ -0,0 +1,79 @@
+import type { LogContext } from '@rocicorp/logger';
+import type postgres from 'postgres';
+import * as v from '../../../shared/src/valita.js';
+import type { PostgresDB, PostgresTransaction } from '../types/pg.js';
+type Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;
+/**
+ * Encapsulates the logic for setting up or upgrading to a new schema. After the
+ * Migration code successfully completes, {@link runSchemaMigrations}
+ * will update the schema version and commit the transaction.
+ */
+export type Migration = {
+    /**
+     * Perform database operations that create or alter table structure. This is
+     * called at most once during lifetime of the application. If a `migrateData()`
+     * operation is defined, that will be performed after `migrateSchema()` succeeds.
+     */
+    migrateSchema?: Operations;
+    /**
+     * Perform database operations to migrate data to the new schema. This is
+     * called after `migrateSchema()` (if defined), and may be called again
+     * to re-migrate data after the server was rolled back to an earlier version,
+     * and rolled forward again.
+     *
+     * Consequently, the logic in `migrateData()` must be idempotent.
+     */
+    migrateData?: Operations;
+    /**
+     * Sets the `minSafeVersion` to the specified value, prohibiting running
+     * any earlier code versions.
+     */
+    minSafeVersion?: number;
+};
+/**
+ * Mapping of incremental migrations to move from the previous old code
+ * version to next one. Versions must be non-zero.
+ *
+ * The schema resulting from performing incremental migrations should be
+ * equivalent to that of the `setupMigration` on a blank database.
+ *
+ * The highest destinationVersion of this map denotes the current
+ * "code version", and is also used as the destination version when
+ * running the initial setup migration on a blank database.
+ */
+export type IncrementalMigrationMap = {
+    [destinationVersion: number]: Migration;
+};
+/**
+ * Ensures that the schema is compatible with the current code, updating and
+ * migrating the schema if necessary.
+ */
+export declare function runSchemaMigrations(log: LogContext, debugName: string, schemaName: string, db: PostgresDB, setupMigration: Migration, incrementalMigrationMap: IncrementalMigrationMap): Promise<void>;
+export declare const versionHistory: v.ObjectType<{
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.Type<number>;
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.Type<number>;
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.Type<number>;
+}, undefined>;
+export type VersionHistory = v.Infer<typeof versionHistory>;
+export declare function getVersionHistory(sql: postgres.Sql, schemaName: string): Promise<VersionHistory>;
+export {};
+//# sourceMappingURL=migration.d.ts.map

package/out/zero-cache/src/db/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,KAAK,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAEpE,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CA+Ef;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAsBzB"}

package/out/zero-cache/src/db/migration.js

@@ -0,0 +1,156 @@
+import { assert } from '../../../shared/src/asserts.js';
+import { randInt } from '../../../shared/src/rand.js';
+import * as v from '../../../shared/src/valita.js';
+/**
+ * Ensures that the schema is compatible with the current code, updating and
+ * migrating the schema if necessary.
+ */
+export async function runSchemaMigrations(log, debugName, schemaName, db, setupMigration, incrementalMigrationMap) {
+    log = log.withContext('initSchema', randInt(0, Number.MAX_SAFE_INTEGER).toString(36));
+    try {
+        const versionMigrations = sorted(incrementalMigrationMap);
+        assert(versionMigrations.length, `Must specify at least one version migration`);
+        assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
+        const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+        log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
+        let versions = await db.begin(async (tx) => {
+            const versions = await getVersionHistory(tx, schemaName);
+            if (codeVersion < versions.minSafeVersion) {
+                throw new Error(`Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`);
+            }
+            if (versions.dataVersion > codeVersion) {
+                log.info?.(`Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`);
+                return updateVersionHistory(log, tx, schemaName, versions, codeVersion);
+            }
+            return versions;
+        });
+        if (versions.dataVersion < codeVersion) {
+            const migrations = versions.dataVersion === 0
+                ? // For the empty database v0, only run the setup migration.
+                    [[codeVersion, setupMigration]]
+                : versionMigrations;
+            for (const [dest, migration] of migrations) {
+                if (versions.dataVersion < dest) {
+                    log.info?.(`Migrating schema from v${versions.dataVersion} to v${dest}`);
+                    void log.flush(); // Flush logs before each migration to help debug crash-y migrations.
+                    versions = await db.begin(async (tx) => {
+                        // Fetch meta from within the transaction to make the migration atomic.
+                        let versions = await getVersionHistory(tx, schemaName);
+                        if (versions.dataVersion < dest) {
+                            versions = await runMigration(log, schemaName, tx, versions, dest, migration);
+                            assert(versions.dataVersion === dest);
+                        }
+                        return versions;
+                    });
+                }
+            }
+        }
+        assert(versions.dataVersion === codeVersion);
+        log.info?.(`Running ${debugName} at schema v${codeVersion}`);
+    }
+    catch (e) {
+        log.error?.('Error in ensureSchemaMigrated', e);
+        throw e;
+    }
+    finally {
+        void log.flush(); // Flush the logs but do not block server progress on it.
+    }
+}
+function sorted(incrementalMigrationMap) {
+    const versionMigrations = [];
+    for (const [v, m] of Object.entries(incrementalMigrationMap)) {
+        versionMigrations.push([Number(v), m]);
+    }
+    return versionMigrations.sort(([a], [b]) => a - b);
+}
+// Exposed for tests.
+export const versionHistory = v.object({
+    /**
+     * The `schemaVersion` is highest code version that has ever been run
+     * on the database, and is used to delineate the structure of the tables
+     * in the database. A schemaVersion only moves forward; rolling back to
+     * an earlier (safe) code version does not revert schema changes that
+     * have already been applied.
+     */
+    schemaVersion: v.number(),
+    /**
+     * The data version is the code version of the latest server that ran.
+     * Note that this may be less than the schemaVersion in the case that
+     * a server is rolled back to an earlier version after a schema change.
+     * In such a case, data (but not schema), may need to be re-migrated
+     * when rolling forward again.
+     */
+    dataVersion: v.number(),
+    /**
+     * The minimum code version that is safe to run. This is used when
+     * a schema migration is not backwards compatible with an older version
+     * of the code.
+     */
+    minSafeVersion: v.number(),
+});
+// Exposed for tests
+export async function getVersionHistory(sql, schemaName) {
+    // Note: The `lock` column transparently ensures that at most one row exists.
+    const results = await sql `
+    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};
+    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}."versionHistory" (
+      "dataVersion" int NOT NULL,
+      "schemaVersion" int NOT NULL,
+      "minSafeVersion" int NOT NULL,
+
+      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',
+      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),
+      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')
+    );
+    SELECT "dataVersion", "schemaVersion", "minSafeVersion" FROM ${sql(schemaName)}."versionHistory";
+  `.simple();
+    const rows = results[1];
+    if (rows.length === 0) {
+        return { schemaVersion: 0, dataVersion: 0, minSafeVersion: 0 };
+    }
+    return v.parse(rows[0], versionHistory);
+}
+async function updateVersionHistory(log, sql, schemaName, prev, newVersion, minSafeVersion) {
+    assert(newVersion > 0);
+    const versions = {
+        dataVersion: newVersion,
+        // The schemaVersion never moves backwards.
+        schemaVersion: Math.max(newVersion, prev.schemaVersion),
+        minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),
+    };
+    await sql `
+    INSERT INTO ${sql(schemaName)}."versionHistory" ${sql(versions)}
+      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}
+  `;
+    return versions;
+}
+async function runMigration(log, schemaName, tx, versions, destinationVersion, migration) {
+    if (versions.schemaVersion < destinationVersion) {
+        await migration.migrateSchema?.(log, tx);
+    }
+    if (versions.dataVersion < destinationVersion) {
+        await migration.migrateData?.(log, tx);
+    }
+    return updateVersionHistory(log, tx, schemaName, versions, destinationVersion, migration.minSafeVersion);
+}
+/**
+ * Bumps the rollback limit [[toAtLeast]] the specified version.
+ * Leaves the rollback limit unchanged if it is equal or greater.
+ */
+function getMinSafeVersion(log, current, proposedSafeVersion) {
+    if (proposedSafeVersion === undefined) {
+        return current.minSafeVersion;
+    }
+    // Sanity check to maintain the invariant that running code is never
+    // earlier than the rollback limit.
+    assert(proposedSafeVersion <= current.dataVersion + 1);
+    if (current.minSafeVersion >= proposedSafeVersion) {
+        // The rollback limit must never move backwards.
+        log.debug?.(`rollback limit is already at ${current.minSafeVersion}, ` +
+            `don't need to bump to ${proposedSafeVersion}`);
+        return current.minSafeVersion;
+    }
+    log.info?.(`bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`);
+    return proposedSafeVersion;
+}
+//# sourceMappingURL=migration.js.map

package/out/zero-cache/src/db/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/db/specs.d.ts

@@ -60,7 +60,7 @@ export declare const liteIndexSpec: v.ObjectType<{
     columns: v.Type<Record<string, "ASC" | "DESC">>;
 }, undefined>;
 export type MutableLiteIndexSpec = v.Infer<typeof liteIndexSpec>;
-export type LiteIndexSpec = DeepReadonly<MutableLiteIndexSpec>;
+export type LiteIndexSpec = Readonly<MutableLiteIndexSpec>;
 export declare const indexSpec: v.ObjectType<Omit<{
     name: v.Type<string>;
     tableName: v.Type<string>;

package/out/zero-cache/src/db/specs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/specs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD,eAAO,MAAM,UAAU;;;;;;aAMrB,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC;AAE9D,eAAO,MAAM,aAAa;;;;;;;;;;aAIxB,CAAC;AAEH,eAAO,MAAM,SAAS;;;;;;;;;;;;aAEpB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;aAE5B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC;AAEpE,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC;AAE5E,eAAO,MAAM,eAAe,8CAA+C,CAAC;AAE5E,eAAO,MAAM,aAAa;;;;;aAKxB,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEjE,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;AAE/D,eAAO,MAAM,SAAS;;;;;;;aAEpB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC"}
+{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/specs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AAEnD,eAAO,MAAM,UAAU;;;;;;aAMrB,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC;AAE9D,eAAO,MAAM,aAAa;;;;;;;;;;aAIxB,CAAC;AAEH,eAAO,MAAM,SAAS;;;;;;;;;;;;aAEpB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;aAE5B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC;AAEpE,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC;AAE5E,eAAO,MAAM,eAAe,8CAA+C,CAAC;AAE5E,eAAO,MAAM,aAAa;;;;;aAKxB,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEjE,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAE3D,eAAO,MAAM,SAAS;;;;;;;aAEpB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC"}