tinybase 2.2.0-beta.0 → 2.2.0-beta.1

package/bin/cli.js

@@ -1,2 +1,2 @@
 #! /usr/bin/env node
-(()=>{const[,,o,...s]=process.argv;if("pwd"!==o)return console.dir(s),void console.log("Commands: [pwd]");console.log(process.cwd())})();
+import{writeFileSync as t,readFileSync as e}from"fs";import{createStore as r}from"tinybase";import{createTools as s}from"tinybase/tools";import{resolve as a}from"path";const o=JSON.parse,i=Object,n=(...t)=>{return e=t=>process.stdout.write(t+"\n"),t.forEach(e);var e},m=t=>o(e(t,"utf8")),p=()=>{var t,e;n("","tinybase <command>","","Usage:",""),t=c,e=([,t,e],r)=>n(` tinybase ${r} ${t}`," - "+e,""),((t,e)=>{t.map(e)})(i.entries(t),(([t,r])=>e(r,t)))},c={help:[p,"","print this message"],version:[()=>n(m("./package.json").version),"","get the current TinyBase version"],getStoreApi:[async(e,o,i)=>{try{const p=s(r().setSchema(m(e))),[c,f]=await p.getPrettyStoreApi(o),h=a(i,o+".d.ts"),u=a(i,o+".ts");t(h,c,"utf8"),t(u,f,"utf8"),n("    Definition: "+h,"Implementation: "+u)}catch{process.stderr.write("ERROR: provide a valid schemaFile, storeName, and outputDir\n")}},"<schemaFile> <storeName> <outputDir>","generate .d.ts and .ts files from a schema file"]};(()=>{const[,,t,...e]=process.argv;(c[t]?.[0]??p)(...e)})();

package/lib/checkpoints.js

@@ -1 +1 @@
-const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,r=e=>0==n(e),s=(e,...t)=>e.push(...t),o=e=>e.pop(),l=e=>e.shift(),c=e=>null==e,i=(e,t,n)=>c(e)?n?.():t(e),a=(e,t)=>e?.has(t)??!1,d=e=>c(e)||0==(e=>e.size)(e),u=(e,t)=>e?.forEach(t),h=(e,t)=>e?.delete(t),p=e=>new Map(e),C=(e,t)=>e?.get(t),g=(e,t,n)=>c(n)?(h(e,t),e):e?.set(t,n),k=(e,t,n)=>(a(e,t)||g(e,t,n()),C(e,t)),f=(e,t,r,s,o=0)=>i((r?k:C)(e,t[o],o>n(t)-2?r:p),(l=>{if(o>n(t)-2)return s?.(l)&&g(e,t[o]),l;const c=f(l,t,r,s,o+1);return d(l)&&g(e,t[o]),c})),v=e=>new Set(Array.isArray(e)||c(e)?e:[e]),L=/^\d+$/,w=e=>{let r;const[o,a]=(()=>{const e=[];let t=0;return[()=>l(e)??""+t++,t=>{L.test(t)&&n(e)<1e3&&s(e,t)}]})(),k=p();return[(t,n,s)=>{r??=e();const l=o();var c,i;return g(k,l,[t,n,s]),c=f(n,s??[""],v),i=l,c?.add(i),l},(e,o,...l)=>t(((e,r=[""])=>{const o=[],l=(e,c)=>c==n(r)?s(o,e):null===r[c]?u(e,(e=>l(e,c+1))):t([r[c],null],(t=>l(C(e,t),c+1)));return l(e,0),o})(e,o),(e=>u(e,(e=>C(k,e)[0](r,...o??[],...l))))),e=>i(C(k,e),(([,t,n])=>(f(t,n??[""],void 0,(t=>(h(t,e),d(t)?1:0))),g(k,e),a(e),n))),(e,s,o)=>i(C(k,e),(([e,,l=[]])=>{const i=(...a)=>{const d=n(a);d==n(l)?e(r,...a,...o(a)):c(l[d])?t(s[d](...a),(e=>i(...a,e))):i(...a,l[d])};i()}))]},S=Object.freeze,y=(e=>{const t=new WeakMap;return n=>(t.has(n)||t.set(n,e(n)),t.get(n))})((h=>{let f,v,L,y=100,z=p(),E=1;const A=p(),I=p(),[M,b,j]=w((()=>Q)),x=p(),B=p(),F=[],O=[],T=(e,t)=>{E=0,h.transaction((()=>u(C(x,t),((t,n)=>u(t,((t,r)=>u(t,((t,s)=>((e,t,n,r,s)=>c(s)?e.delCell(t,n,r,!0):e.setCell(t,n,r,s))(h,n,r,s,t[e]))))))))),E=1},W=e=>{g(x,e),g(B,e),b(I,[e])},$=(e,r)=>t(((e,t)=>e.splice(0,t))(e,r??n(e)),W),m=()=>$(F,n(F)-y),q=h.addCellListener(null,null,null,((e,t,n,r,l,c)=>{if(E){i(f,(()=>{s(F,f),m(),$(O),f=void 0,L=1}));const e=k(z,t,p),a=k(e,n,p),u=k(a,r,(()=>[c,void 0]));u[1]=l,u[0]===l&&d(g(a,r))&&d(g(e,n))&&d(g(z,t))&&(f=o(F),L=1),J()}})),D=(e="")=>(c(f)&&(f=""+v++,g(x,f,z),N(f,e),z=p(),L=1),f),G=()=>{r(F)||(((e,...t)=>{e.unshift(...t)})(O,D()),T(0,f),f=o(F),L=1)},H=()=>{r(O)||(s(F,f),f=l(O),T(1,f),L=1)},J=()=>{L&&(b(A),L=0)},K=e=>{const t=D(e);return J(),t},N=(e,t)=>(P(e)&&C(B,e)!==t&&(g(B,e,t),b(I,[e])),Q),P=e=>a(x,e),Q={setSize:e=>(y=e,m(),Q),addCheckpoint:K,setCheckpoint:N,getStore:()=>h,getCheckpointIds:()=>[[...F],f,[...O]],forEachCheckpoint:e=>{return t=e,u(B,((e,n)=>t(n,e)));var t},hasCheckpoint:P,getCheckpoint:e=>C(B,e),goBackward:()=>(G(),J(),Q),goForward:()=>(H(),J(),Q),goTo:t=>{const n=e(F,t)?G:e(O,t)?H:null;for(;!c(n)&&t!=f;)n();return J(),Q},addCheckpointIdsListener:e=>M(e,A),addCheckpointListener:(e,t)=>M(t,I,[e]),delListener:e=>(j(e),Q),clear:()=>($(F),$(O),c(f)||W(f),f=void 0,v=0,K(),Q),destroy:()=>{h.delListener(q)},getListenerStats:()=>({})};return S(Q.clear())}));export{y as createCheckpoints};
+const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,r=e=>0==n(e),s=(e,...t)=>e.push(...t),o=e=>e.pop(),l=e=>e.shift(),c=e=>null==e,i=(e,t,n)=>c(e)?n?.():t(e),a=(e,t)=>e?.has(t)??!1,d=e=>c(e)||0==(e=>e.size)(e),u=(e,t)=>e?.forEach(t),h=(e,t)=>e?.delete(t),p=e=>new Map(e),C=(e,t)=>e?.get(t),g=(e,t,n)=>c(n)?(h(e,t),e):e?.set(t,n),k=(e,t,n)=>(a(e,t)||g(e,t,n()),C(e,t)),f=(e,t,r,s,o=0)=>i((r?k:C)(e,t[o],o>n(t)-2?r:p),(l=>{if(o>n(t)-2)return s?.(l)&&g(e,t[o]),l;const c=f(l,t,r,s,o+1);return d(l)&&g(e,t[o]),c})),v=e=>new Set(Array.isArray(e)||c(e)?e:[e]),L=/^\d+$/,w=Object.freeze,S=(S=>{const y=new WeakMap;return S=>(y.has(S)||y.set(S,(S=>{let y,z,E,A=100,I=p(),M=1;const b=p(),j=p(),[x,B,F]=(e=>{let r;const[o,a]=(()=>{const e=[];let t=0;return[()=>l(e)??""+t++,t=>{L.test(t)&&n(e)<1e3&&s(e,t)}]})(),k=p();return[(e,t,n)=>{r??=V;const s=o();var l;return g(k,s,[e,t,n]),l=s,f(t,n??[""],v)?.add(l),s},(e,o,...l)=>t(((e,r=[""])=>{const o=[],l=(e,c)=>c==n(r)?s(o,e):null===r[c]?u(e,(e=>l(e,c+1))):t([r[c],null],(t=>l(C(e,t),c+1)));return l(e,0),o})(e,o),(e=>u(e,(e=>C(k,e)[0](r,...o??[],...l))))),e=>i(C(k,e),(([,t,n])=>(f(t,n??[""],void 0,(t=>(h(t,e),d(t)?1:0))),g(k,e),a(e),n))),(e,s,o)=>i(C(k,e),(([e,,l=[]])=>{const i=(...a)=>{const d=n(a);d==n(l)?e(r,...a,...o(a)):c(l[d])?t(s[d](...a),(e=>i(...a,e))):i(...a,l[d])};i()}))]})(),O=p(),T=p(),W=[],$=[],m=(e,t)=>{M=0,S.transaction((()=>u(C(O,t),((t,n)=>u(t,((t,r)=>u(t,((t,s)=>((e,t,n,r,s)=>c(s)?e.delCell(t,n,r,!0):e.setCell(t,n,r,s))(S,n,r,s,t[e]))))))))),M=1},q=e=>{g(O,e),g(T,e),B(j,[e])},D=(e,r)=>t(((e,t)=>e.splice(0,t))(e,r??n(e)),q),G=()=>D(W,n(W)-A),H=S.addCellListener(null,null,null,((e,t,n,r,l,c)=>{if(M){i(y,(()=>{s(W,y),G(),D($),y=void 0,E=1}));const e=k(I,t,p),a=k(e,n,p),u=k(a,r,(()=>[c,void 0]));u[1]=l,u[0]===l&&d(g(a,r))&&d(g(e,n))&&d(g(I,t))&&(y=o(W),E=1),P()}})),J=(e="")=>(c(y)&&(y=""+z++,g(O,y,I),R(y,e),I=p(),E=1),y),K=()=>{r(W)||(((e,...t)=>{e.unshift(...t)})($,J()),m(0,y),y=o(W),E=1)},N=()=>{r($)||(s(W,y),y=l($),m(1,y),E=1)},P=()=>{E&&(B(b),E=0)},Q=e=>{const t=J(e);return P(),t},R=(e,t)=>(U(e)&&C(T,e)!==t&&(g(T,e,t),B(j,[e])),V),U=e=>a(O,e),V={setSize:e=>(A=e,G(),V),addCheckpoint:Q,setCheckpoint:R,getStore:()=>S,getCheckpointIds:()=>[[...W],y,[...$]],forEachCheckpoint:e=>{return t=e,u(T,((e,n)=>t(n,e)));var t},hasCheckpoint:U,getCheckpoint:e=>C(T,e),goBackward:()=>(K(),P(),V),goForward:()=>(N(),P(),V),goTo:t=>{const n=e(W,t)?K:e($,t)?N:null;for(;!c(n)&&t!=y;)n();return P(),V},addCheckpointIdsListener:e=>x(e,b),addCheckpointListener:(e,t)=>x(t,j,[e]),delListener:e=>(F(e),V),clear:()=>(D(W),D($),c(y)||q(y),y=void 0,z=0,Q(),V),destroy:()=>{S.delListener(H)},getListenerStats:()=>({})};return w(V.clear())})(S)),y.get(S))})();export{S as createCheckpoints};

package/lib/debug/queries.js

@@ -24,6 +24,7 @@ const arrayIsEqual = (array1, array2) =>
   arrayLength(array1) === arrayLength(array2) &&
   arrayEvery(array1, (value1, index) => array2[index] === value1);
 const arrayForEach = (array, cb) => array.forEach(cb);
+const arrayMap = (array, cb) => array.map(cb);
 const arraySum = (array) => arrayReduce(array, (i, j) => i + j, 0);
 const arrayLength = (array) => array.length;
 const arrayIsEmpty = (array) => arrayLength(array) == 0;
@@ -329,8 +330,8 @@ const getCreateFunction = (getFunction) => {
 
 const object = Object;
 const objFreeze = object.freeze;
-const objForEach = (obj, cb) =>
-  arrayForEach(object.entries(obj), ([id, value]) => cb(value, id));
+const objMap = (obj, cb) =>
+  arrayMap(object.entries(obj), ([id, value]) => cb(value, id));
 
 const createQueries = getCreateFunction((store) => {
   const createStore = store.createStore;
@@ -744,7 +745,7 @@ const createQueries = getCreateFunction((store) => {
     destroy,
     getListenerStats,
   };
-  objForEach(
+  objMap(
     {
       [TABLE]: [1, 1],
       [ROW_IDS]: [0, 1],

package/lib/debug/store.js

@@ -134,8 +134,8 @@ const isObject = (obj) =>
 const objGet = (obj, id) => ifNotUndefined(obj, (obj2) => obj2[id]);
 const objHas = (obj, id) => !isUndefined(objGet(obj, id));
 const objDel = (obj, id) => delete obj[id];
-const objForEach = (obj, cb) =>
-  arrayForEach(object.entries(obj), ([id, value]) => cb(value, id));
+const objMap = (obj, cb) =>
+  arrayMap(object.entries(obj), ([id, value]) => cb(value, id));
 const objIsEmpty = (obj) => arrayIsEmpty(objIds(obj));
 
 const setNew = (entryOrEntries) =>
@@ -248,7 +248,7 @@ const validate = (obj, validateChild, onInvalidObj) => {
     onInvalidObj?.();
     return false;
   }
-  objForEach(obj, (child, id2) => {
+  objMap(obj, (child, id2) => {
     if (!validateChild(child, id2)) {
       objDel(obj, id2);
     }
@@ -711,7 +711,7 @@ const createStore = () => {
       (tableId2, rowId2) => {
         if (validateRow(tableId2, rowId2, partialRow, 1)) {
           const table = getOrCreateTable(tableId2);
-          objForEach(partialRow, (cell, cellId) =>
+          objMap(partialRow, (cell, cellId) =>
             setCellIntoDefaultRow(tableId2, table, rowId2, cellId, cell),
           );
         }
@@ -1005,7 +1005,7 @@ const createStore = () => {
     getListenerStats,
     createStore,
   };
-  objForEach(
+  objMap(
     {
       [TABLES]: [0, tablesListeners],
       [TABLE_IDS]: [0, tableIdsListeners],

package/lib/debug/tinybase.js

@@ -392,8 +392,8 @@ const isObject = (obj) =>
 const objGet = (obj, id) => ifNotUndefined(obj, (obj2) => obj2[id]);
 const objHas = (obj, id) => !isUndefined(objGet(obj, id));
 const objDel = (obj, id) => delete obj[id];
-const objForEach = (obj, cb) =>
-  arrayForEach(object.entries(obj), ([id, value]) => cb(value, id));
+const objMap = (obj, cb) =>
+  arrayMap(object.entries(obj), ([id, value]) => cb(value, id));
 const objIsEmpty = (obj) => arrayIsEmpty(objIds(obj));
 
 const getCellType = (cell) => {
@@ -1546,7 +1546,7 @@ const createQueries = getCreateFunction((store) => {
     destroy,
     getListenerStats,
   };
-  objForEach(
+  objMap(
     {
       [TABLE]: [1, 1],
       [ROW_IDS]: [0, 1],
@@ -1780,7 +1780,7 @@ const validate = (obj, validateChild, onInvalidObj) => {
     onInvalidObj?.();
     return false;
   }
-  objForEach(obj, (child, id2) => {
+  objMap(obj, (child, id2) => {
     if (!validateChild(child, id2)) {
       objDel(obj, id2);
     }
@@ -2243,7 +2243,7 @@ const createStore = () => {
       (tableId2, rowId2) => {
         if (validateRow(tableId2, rowId2, partialRow, 1)) {
           const table = getOrCreateTable(tableId2);
-          objForEach(partialRow, (cell, cellId) =>
+          objMap(partialRow, (cell, cellId) =>
             setCellIntoDefaultRow(tableId2, table, rowId2, cellId, cell),
           );
         }
@@ -2537,7 +2537,7 @@ const createStore = () => {
     getListenerStats,
     createStore,
   };
-  objForEach(
+  objMap(
     {
       [TABLES]: [0, tablesListeners],
       [TABLE_IDS]: [0, tableIdsListeners],

package/lib/debug/tools.d.ts

@@ -224,21 +224,171 @@ export interface Tools {
 
   /**
    * The getStoreApi method returns a code-generated .d.ts file and a .ts file
-   * that wraps the schema of a Store.
+   * that describe the schema of a Store in an ORM style.
    *
-   * This is currently in development, and further documentation is to come.
+   * If the Store does not already have an explicit Schema associated with it,
+   * the data in the Store will be scanned to attempt to infer a new Schema. The
+   * method returns two strings (which should be saved as files) though if no
+   * schema can be inferred, the strings will be empty.
+   *
+   * The method takes a single argument which represents the name you want the
+   * generated store object to have in code. You are expected to save the files
+   * as `[storeName].d.ts` and `[storeName].ts`, and alongside each other so
+   * that the latter can import types from the former.
+   *
+   * The .d.ts and .ts files that are generated are designed to resemble the
+   * main TinyBase `store.d.ts` and `store.ts` files, but provide named types
+   * and methods that describe the domain of the schema in the store.
+   *
+   * For example, from a Store that has a `pets` Table, you will get methods
+   * like `getPetsTable`, and types like `PetsRow`, that are more specific
+   * versions of the underlying getTable method or the Row type. For example:
+   *
+   * |Store type|Equivalent generated type|
+   * |-|-|
+   * |Table|[Table]Table|
+   * |Row|[Table]Row|
+   * |(Cell) Id|[Table]CellId|
+   * |CellCallback|[Table]CellCallback|
+   * |...|...|
+   *
+   * |Store method|Equivalent generated method|
+   * |-|-|
+   * |setTable|set[Table]Table|
+   * |hasRow|has[Table]Row|
+   * |getCell|get[Table][Cell]Cell|
+   * |...|...|
+   *
+   * Equivalent to the TinyBase createStore function, a `create[StoreName]`
+   * function will also be created. This acts as the main entry point to the
+   * generated implementation.
+   *
+   * Each method is refined correctly to take, or return, the types specified by
+   * the schema. For example, if the `pets` Table has a numeric `price` Cell in
+   * the schema, the `getPetsPriceCell` method will be typed to return a number.
+   *
+   * The tables above include just a sample of the generated output. For the
+   * full set of methods and types generated by this method, inspect the output
+   * directly.
+   *
+   * @param storeName The name you want to provide to the generated Store, which
+   * should also be used to save the `.d.ts` and `.ts` files.
+   * @returns A pair of strings representing the contents of the `.d.ts` and
+   * `.ts` files.
+   * @example
+   * This example creates a Tools object and generates code for a Store that
+   * already has a Schema.
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     price: {type: 'number'},
+   *   },
+   * });
+   * const [dTs, ts] = createTools(store).getStoreApi('shop');
+   *
+   * const dTsLines = dTs.split('\n');
+   * console.log(dTsLines[3]);
+   * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
+   * console.log(dTsLines[6]);
+   * // -> 'export type PetsRow = {\'price\'?: number;};'
+   *
+   * const tsLines = ts.split('\n');
+   * console.log(tsLines[40]);
+   * // -> 'getPetsTable: (): PetsTable => store.getTable(PETS) as PetsTable,'
+   * ```
+   * @example
+   * This example creates a Tools object and generates code for a Store that
+   * doesn't already have a Schema.
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {price: 5},
+   *   felix: {price: 4},
+   * });
+   * const [dTs, ts] = createTools(store).getStoreApi('shop');
    *
+   * const dTsLines = dTs.split('\n');
+   * console.log(dTsLines[3]);
+   * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
+   * console.log(dTsLines[6]);
+   * // -> 'export type PetsRow = {\'price\': number;};'
+   *
+   * const tsLines = ts.split('\n');
+   * console.log(tsLines[42]);
+   * // -> 'getPetsTable: (): PetsTable => store.getTable(PETS) as PetsTable,'
+   * ```
    * @category Modelling
    * @since v2.2.0
    */
   getStoreApi(storeName: string): [string, string];
 
   /**
-   * The getStoreApi method attempts to return a prettified code-generated .d.ts
-   * file and a .ts file that wraps the schema of a Store.
+   * The getPrettyStoreApi method attempts to returns a prettified
+   * code-generated .d.ts file and a .ts file that describe the schema of a
+   * Store in an ORM style.
+   *
+   * This is simply a wrapper around the getStoreApi method that attempts to
+   * invoke the `prettier` module (which it hopes you have installed) to format
+   * the generated code. If `prettier` is not present, the output will resemble
+   * that of the underlying getStoreApi method.
    *
-   * This is currently in development, and further documentation is to come.
+   * The method is asynchronous, so you should use the `await` keyword or handle
+   * the results as a promise.
    *
+   * The method takes a single argument which represents the name you want the
+   * generated store object to have in code. You are expected to save the files
+   * as `[storeName].d.ts` and `[storeName].ts`, and alongside each other so
+   * that the latter can import types from the former.
+   *
+   * See the documentation for the getStoreApi method for details of the content
+   * of the generated files.
+   *
+   * @param storeName The name you want to provide to the generated Store, which
+   * should also be used to save the `.d.ts` and `.ts` files.
+   * @returns A pair of strings representing the contents of the `.d.ts` and
+   * `.ts` files.
+   * @example
+   * This example creates a Tools object and generates code for a Store that
+   * already has a Schema.
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     price: {type: 'number'},
+   *   },
+   * });
+   * const tools = createTools(store);
+   * const [dTs, ts] = await tools.getPrettyStoreApi('shop');
+   *
+   * const dTsLines = dTs.split('\n');
+   * console.log(dTsLines[14]);
+   * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
+   * console.log(dTsLines[19]);
+   * // -> 'export type PetsRow = {price?: number};'
+   *
+   * const tsLines = ts.split('\n');
+   * console.log(tsLines[73]);
+   * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
+   * ```
+   * @example
+   * This example creates a Tools object and generates code for a Store that
+   * doesn't already have a Schema.
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {price: 5},
+   *   felix: {price: 4},
+   * });
+   * const tools = createTools(store);
+   * const [dTs, ts] = await tools.getPrettyStoreApi('shop');
+   *
+   * const dTsLines = dTs.split('\n');
+   * console.log(dTsLines[14]);
+   * // -> 'export type PetsTable = {[rowId: Id]: PetsRow};'
+   * console.log(dTsLines[19]);
+   * // -> 'export type PetsRow = {price: number};'
+   *
+   * const tsLines = ts.split('\n');
+   * console.log(tsLines[75]);
+   * // -> '    hasPetsTable: (): boolean => store.hasTable(PETS),'
+   * ```
    * @category Modelling
    * @since v2.2.0
    */