json-fs-query 3.4.0 → 3.5.0

package/dist/cli/output.d.ts

@@ -0,0 +1,31 @@
+import { Markers } from './formatResult';
+export declare const outputFormats: readonly ["table", "json", "csv", "dump"];
+export type OutputFormat = typeof outputFormats[number];
+/**
+ * How results print: the format (-o / /output), and the table's markers for missing and null (--missing, --null, or
+ * /missing and /null at the prompt). The prompt changes these during a session, so one object is shared.
+ */
+export type OutputSettings = {
+    format: OutputFormat;
+    markers: Partial<Markers>;
+};
+/**
+ * Refuse a format that can't print yet, before the query runs (so `-o dump -q "insert ..."` doesn't insert and then
+ * fail to show it).
+ * @param settings
+ * @throws {Error} For dump, which needs the record's name and query() results don't carry it.
+ */
+export declare const assertPrintable: (settings: OutputSettings) => void;
+/**
+ * Print each query's result in the chosen format, each followed by a blank line (as psql does) so results stay apart
+ * when several print in a row. Several JSON results are one JSON value each, which jq reads as a stream.
+ * @param {Array<*>} results One result per query
+ * @param settings
+ */
+export declare const printResults: (results: Array<unknown>, settings: OutputSettings) => void;
+/**
+ * Print an error in red, without its stack.
+ * @param {*} error
+ */
+export declare const printError: (error: unknown) => void;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.printResults = exports.printError = exports.outputFormats = exports.assertPrintable = void 0;
+require("core-js/modules/es.json.stringify.js");
+var _util = require("util");
+var _formatCsv = require("./formatCsv");
+var _formatResult = require("./formatResult");
+const outputFormats = exports.outputFormats = ['table', 'json', 'csv', 'dump'];
+// Dim the markers only on a terminal, and never with NO_COLOR set (https://no-color.org)
+const color = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+/**
+ * Refuse a format that can't print yet, before the query runs (so `-o dump -q "insert ..."` doesn't insert and then
+ * fail to show it).
+ * @param settings
+ * @throws {Error} For dump, which needs the record's name and query() results don't carry it.
+ */
+const assertPrintable = settings => {
+  if (settings.format === 'dump') {
+    throw new Error('dump output isn\'t available yet (it needs the record\'s name, which results don\'t carry): use table, json or csv');
+  }
+};
+/**
+ * Format one result in the chosen format.
+ * @param result
+ * @param settings
+ * @returns {string}
+ */
+exports.assertPrintable = assertPrintable;
+const format = (result, settings) => {
+  switch (settings.format) {
+    case 'json':
+      return JSON.stringify(result, null, 2);
+    case 'csv':
+      return (0, _formatCsv.formatCsv)(result);
+    default:
+      return (0, _formatResult.formatResult)(result, {
+        color: color(),
+        markers: settings.markers
+      });
+  }
+};
+/**
+ * Print each query's result in the chosen format, each followed by a blank line (as psql does) so results stay apart
+ * when several print in a row. Several JSON results are one JSON value each, which jq reads as a stream.
+ * @param {Array<*>} results One result per query
+ * @param settings
+ */
+const printResults = (results, settings) => {
+  for (const result of results) {
+    console.log(`${format(result, settings)}\n`);
+  }
+};
+/**
+ * Print an error in red, without its stack.
+ * @param {*} error
+ */
+exports.printResults = printResults;
+const printError = error => {
+  console.error((0, _util.styleText)('red', `Error: ${error instanceof Error ? error.message : String(error)}`));
+};
+exports.printError = printError;

package/dist/cli/output.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.printResults=exports.printError=exports.outputFormats=exports.assertPrintable=void 0,require("core-js/modules/es.json.stringify.js");var _util=require("util"),_formatCsv=require("./formatCsv"),_formatResult=require("./formatResult");const outputFormats=exports.outputFormats=["table","json","csv","dump"],color=()=>Boolean(process.stdout.isTTY)&&!process.env.NO_COLOR,assertPrintable=r=>{if("dump"===r.format)throw new Error("dump output isn't available yet (it needs the record's name, which results don't carry): use table, json or csv")};exports.assertPrintable=assertPrintable;const format=(r,t)=>{switch(t.format){case"json":return JSON.stringify(r,null,2);case"csv":return(0,_formatCsv.formatCsv)(r);default:return(0,_formatResult.formatResult)(r,{color:color(),markers:t.markers})}},printResults=(r,t)=>{for(const s of r)console.log(`${format(s,t)}\n`)};exports.printResults=printResults;const printError=r=>{console.error((0,_util.styleText)("red",`Error: ${r instanceof Error?r.message:String(r)}`))};exports.printError=printError;

package/dist/cli/runDirect.d.ts

@@ -0,0 +1,11 @@
+import { DatabaseOptions } from './chooseDatabase';
+import { OutputSettings } from './output';
+/**
+ * Run one query string (one or more queries) without opening the prompt: print each result, or the error.
+ * @param queryString What `-q` / `--query` was given
+ * @param options The database options
+ * @param settings The output format and markers
+ * @returns {Promise<number>} The exit code: 0, or 1 when choosing the database or the query failed.
+ */
+export declare const runDirect: (queryString: string, options: DatabaseOptions, settings: OutputSettings) => Promise<number>;
+//# sourceMappingURL=runDirect.d.ts.map

package/dist/cli/runDirect.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runDirect = void 0;
+var _query = require("../data/queries/query");
+var _chooseDatabase = require("./chooseDatabase");
+var _output = require("./output");
+/**
+ * Run one query string (one or more queries) without opening the prompt: print each result, or the error.
+ * @param queryString What `-q` / `--query` was given
+ * @param options The database options
+ * @param settings The output format and markers
+ * @returns {Promise<number>} The exit code: 0, or 1 when choosing the database or the query failed.
+ */
+const runDirect = async (queryString, options, settings) => {
+  try {
+    (0, _output.assertPrintable)(settings);
+    await (0, _chooseDatabase.chooseDatabase)(options);
+    (0, _output.printResults)(await (0, _query.query)(queryString), settings);
+    return 0;
+  } catch (error) {
+    (0, _output.printError)(error);
+    return 1;
+  }
+};
+exports.runDirect = runDirect;

package/dist/cli/runDirect.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.runDirect=void 0;var _query=require("../data/queries/query"),_chooseDatabase=require("./chooseDatabase"),_output=require("./output");const runDirect=async(e,r,t)=>{try{return(0,_output.assertPrintable)(t),await(0,_chooseDatabase.chooseDatabase)(r),(0,_output.printResults)(await(0,_query.query)(e),t),0}catch(e){return(0,_output.printError)(e),1}};exports.runDirect=runDirect;

package/dist/data/introspect/alter.js

@@ -5,10 +5,10 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.alter = void 0;
 require("core-js/modules/es.array.includes.js");
-require("core-js/modules/es.json.stringify.js");
 var _field = require("./definitions/field");
 var _create = require("./create");
 var _parseCreate = require("../utilities/parsers/parseCreate");
+var _assertValidName = require("../utilities/assertValidName");
 var _retrieveRecord = require("../utilities/retrieveRecord");
 var _retrieveFiles = require("../utilities/retrieveFiles");
 var _retrieveRecords = require("../utilities/retrieveRecords");
@@ -278,10 +278,7 @@ const alter = async (entity, change) => {
   // The same names the query language allows: a name becomes a key in every row and part of index file paths, so
   // one like `../x` from a direct call must not get that far
   const names = [entity, ...('field' in change ? [change.field?.name] : []), ...('name' in change ? [change.name] : []), ...('to' in change ? [change.to] : [])];
-  const invalid = names.findIndex(name => typeof name !== 'string' || !_parseCreate.nameMatch.test(name));
-  if (invalid !== -1) {
-    throw new Error(`Invalid name ${JSON.stringify(names[invalid]) ?? 'undefined'} in alter: names use letters, digits, _ and - only`);
-  }
+  names.forEach(name => (0, _assertValidName.assertValidName)(name, 'alter'));
   const record = await (0, _retrieveRecord.retrieveRecord)(entity);
   switch (change.action) {
     case 'add':

package/dist/data/introspect/alter.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.alter=void 0,require("core-js/modules/es.array.includes.js"),require("core-js/modules/es.json.stringify.js");var _field=require("./definitions/field"),_create=require("./create"),_parseCreate=require("../utilities/parsers/parseCreate"),_retrieveRecord=require("../utilities/retrieveRecord"),_retrieveFiles=require("../utilities/retrieveFiles"),_retrieveRecords=require("../utilities/retrieveRecords"),_knownFields=require("../utilities/knownFields"),_packedTable=require("../utilities/packedTable"),_requireNode=require("../utilities/requireNode"),_showRecords=require("../queries/showRecords"),_updateEntity=require("../queries/updateEntity"),_typeCheck=require("./policies/typeCheck"),_storage=require("../storage");const rowsOf=async e=>(await(0,_retrieveFiles.retrieveFiles)(e.entries.map((t=>`${e.path}/${t}`)),_retrieveRecords.retrieveEntry)).map(((t,i)=>({fileName:e.entries[i],data:t}))),has=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),keysUsing=(e,t)=>e.keys.filter((e=>e.fields.includes(t))),describeKey=e=>`${e.type} key (${e.fields.join(", ")})`,referencesTo=async(e,t)=>{const i=[];for(const r of await(0,_showRecords.showRecords)()){const a=await(0,_retrieveRecord.retrieveRecord)(r);for(const n of a.keys)"foreign"===n.type&&(n.references||[]).some((i=>i.fields.includes(`${e}.${t}`)))&&i.push({entity:r,record:a,key:n})}return i},writeRecord=async(e,t)=>{(0,_create.assertValidDefinition)(e,t),await(0,_storage.writeJson)(`${e}.json`,t)},setField=async(e,t,i,r,a)=>{if(i.length)if(await(0,_packedTable.discardPacked)(t.path),keysUsing(t,r).length&&"function"!=typeof a){if(!t.keys.some((e=>"primary"===e.type)))throw new Error(`Can't change "${r}" on ${e}'s rows: a key uses it, and rows are found by the primary key, which ${e} doesn't have`);await(0,_updateEntity.updateEntity)(e,{[r]:void 0===a?null:a},{[e]:i.map((e=>e.data))})}else for(const e of i){const i=Object.assign({},e.data),n="function"==typeof a?a(e):a;void 0===n?delete i[r]:i[r]=n,await(0,_storage.writeJson)(`${t.path}/${e.fileName}`,i)}},addField=async(e,t,i)=>{if(t.definition.some((e=>e.name===i.name)))throw new Error(`Field "${i.name}" already exists on ${e}`);const r={...t,definition:[...t.definition,i]},a=await rowsOf(t);for(const t of a.filter((e=>has(e.data,i.name))))try{(0,_typeCheck.typeCheck)(i.type,t.data[i.name],i.nullable)}catch(r){throw new Error(`Can't add "${i.name}" to ${e}: row ${t.fileName} already holds a value for it that doesn't fit (${r.message})`)}const n=a.filter((e=>!has(e.data,i.name))),o=has(i,"default");if(n.length&&!i.optional&&!o&&!i.autoGenerate)throw new Error(`Can't add required field "${i.name}" to ${e}: its ${n.length} row(s) have no value for it (give it a default, or make it optional)`);return await writeRecord(e,r),i.autoGenerate?await setField(e,r,n,i.name,(()=>crypto.randomUUID())):o&&await setField(e,r,n,i.name,i.default),r},dropField=async(e,t,i)=>{(0,_knownFields.assertFieldsDefined)(e,t,[i],"alter");const r=keysUsing(t,i)[0];if(r)throw new Error(`Can't drop "${i}" from ${e}: its ${describeKey(r)} uses it`);const a=(await referencesTo(e,i))[0];if(a)throw new Error(`Can't drop "${i}" from ${e}: ${a.entity}'s foreign key "${a.key.fields[0]}" references it`);const n={...t,definition:t.definition.filter((e=>e.name!==i))};return await writeRecord(e,n),await setField(e,n,(await rowsOf(t)).filter((e=>has(e.data,i))),i,void 0),n},renameField=async(e,t,i,r)=>{if((0,_knownFields.assertFieldsDefined)(e,t,[i],"alter"),t.definition.some((e=>e.name===r)))throw new Error(`Can't rename "${i}" on ${e} to "${r}": a field of that name already exists`);const a=await referencesTo(e,i),n=t.keys.map((e=>{if(!e.fields.includes(i))return e;const t=e.fields.map((e=>e===i?r:e)),a=e.lookup&&e.lookup===(0,_parseCreate.keyLookup)(e.type,e.fields)?(0,_parseCreate.keyLookup)(e.type,t):e.lookup;return{...e,fields:t,lookup:a}})),o=t=>"foreign"!==t.type?t:{...t,references:(t.references||[]).map((t=>({...t,fields:t.fields.map((t=>t===`${e}.${i}`?`${e}.${r}`:t))})))},s={...t,definition:t.definition.map((e=>e.name===i?{...e,name:r}:e)),keys:n.map(o)};for(const[e,i]of t.keys.entries()){const r=n[e].lookup;i.lookup&&r!==i.lookup&&(0,_storage.fileExists)(`__indexes/${t.path}/${i.lookup}`)&&(await(0,_storage.writeJson)(`__indexes/${t.path}/${r}`,await(0,_storage.readJson)(`__indexes/${t.path}/${i.lookup}`)),await(0,_storage.removeFile)(`__indexes/${t.path}/${i.lookup}`))}await writeRecord(e,s);for(const t of a.filter((t=>t.entity!==e)))await(0,_storage.writeJson)(`${t.entity}.json`,{...t.record,keys:t.record.keys.map(o)});const d=(await rowsOf(t)).filter((e=>has(e.data,i)));d.length&&await(0,_packedTable.discardPacked)(t.path);for(const e of d){const a=Object.assign({},e.data);a[r]=a[i],delete a[i],await(0,_storage.writeJson)(`${t.path}/${e.fileName}`,a)}return s},modifyField=async(e,t,i)=>{(0,_knownFields.assertFieldsDefined)(e,t,[i.name],"alter");const r=t.definition.find((e=>e.name===i.name));if(r.type!==i.type)throw new Error(`Can't change the type of "${i.name}" on ${e} (${r.type} to ${i.type}): only optional, null and default can change`);if(Boolean(r.autoGenerate)!==Boolean(i.autoGenerate))throw new Error(`Can't change whether "${i.name}" on ${e} is auto: only optional, null and default can change`);const a={...t,definition:t.definition.map((e=>e.name===i.name?i:e))},n=await rowsOf(t),o=has(i,"default"),s=i.nullable?[]:n.filter((e=>null===e.data[i.name])),d=i.optional?[]:n.filter((e=>!has(e.data,i.name))),l=i.optional?[]:s;if((d.length||l.length)&&!o)throw d.length?new Error(`Can't make "${i.name}" required on ${e}: ${d.length} row(s) have no value for it (give it a default to fill them in)`):new Error(`Can't make "${i.name}" not null on ${e}: ${l.length} row(s) hold null (give it a default to fill them in, or make it optional)`);return await writeRecord(e,a),o&&await setField(e,a,[...d,...l],i.name,i.default),i.optional&&s.length&&await setField(e,a,s,i.name,void 0),a},alter=async(e,t)=>{if((0,_requireNode.requireNode)("alter"),"__RECORDS"===e)throw new Error("__RECORDS is reserved for the list of records");const i=[e,..."field"in t?[t.field?.name]:[],..."name"in t?[t.name]:[],..."to"in t?[t.to]:[]],r=i.findIndex((e=>"string"!=typeof e||!_parseCreate.nameMatch.test(e)));if(-1!==r)throw new Error(`Invalid name ${JSON.stringify(i[r])??"undefined"} in alter: names use letters, digits, _ and - only`);const a=await(0,_retrieveRecord.retrieveRecord)(e);switch(t.action){case"add":return(await addField(e,a,(0,_field.field)(t.field))).definition;case"drop":return(await dropField(e,a,t.name)).definition;case"rename":return(await renameField(e,a,t.name,t.to)).definition;case"modify":return(await modifyField(e,a,(0,_field.field)(t.field))).definition;default:throw new Error(`Unknown alter action: ${t.action}`)}};exports.alter=alter;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.alter=void 0,require("core-js/modules/es.array.includes.js");var _field=require("./definitions/field"),_create=require("./create"),_parseCreate=require("../utilities/parsers/parseCreate"),_assertValidName=require("../utilities/assertValidName"),_retrieveRecord=require("../utilities/retrieveRecord"),_retrieveFiles=require("../utilities/retrieveFiles"),_retrieveRecords=require("../utilities/retrieveRecords"),_knownFields=require("../utilities/knownFields"),_packedTable=require("../utilities/packedTable"),_requireNode=require("../utilities/requireNode"),_showRecords=require("../queries/showRecords"),_updateEntity=require("../queries/updateEntity"),_typeCheck=require("./policies/typeCheck"),_storage=require("../storage");const rowsOf=async e=>(await(0,_retrieveFiles.retrieveFiles)(e.entries.map((t=>`${e.path}/${t}`)),_retrieveRecords.retrieveEntry)).map(((t,a)=>({fileName:e.entries[a],data:t}))),has=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),keysUsing=(e,t)=>e.keys.filter((e=>e.fields.includes(t))),describeKey=e=>`${e.type} key (${e.fields.join(", ")})`,referencesTo=async(e,t)=>{const a=[];for(const i of await(0,_showRecords.showRecords)()){const r=await(0,_retrieveRecord.retrieveRecord)(i);for(const o of r.keys)"foreign"===o.type&&(o.references||[]).some((a=>a.fields.includes(`${e}.${t}`)))&&a.push({entity:i,record:r,key:o})}return a},writeRecord=async(e,t)=>{(0,_create.assertValidDefinition)(e,t),await(0,_storage.writeJson)(`${e}.json`,t)},setField=async(e,t,a,i,r)=>{if(a.length)if(await(0,_packedTable.discardPacked)(t.path),keysUsing(t,i).length&&"function"!=typeof r){if(!t.keys.some((e=>"primary"===e.type)))throw new Error(`Can't change "${i}" on ${e}'s rows: a key uses it, and rows are found by the primary key, which ${e} doesn't have`);await(0,_updateEntity.updateEntity)(e,{[i]:void 0===r?null:r},{[e]:a.map((e=>e.data))})}else for(const e of a){const a=Object.assign({},e.data),o="function"==typeof r?r(e):r;void 0===o?delete a[i]:a[i]=o,await(0,_storage.writeJson)(`${t.path}/${e.fileName}`,a)}},addField=async(e,t,a)=>{if(t.definition.some((e=>e.name===a.name)))throw new Error(`Field "${a.name}" already exists on ${e}`);const i={...t,definition:[...t.definition,a]},r=await rowsOf(t);for(const t of r.filter((e=>has(e.data,a.name))))try{(0,_typeCheck.typeCheck)(a.type,t.data[a.name],a.nullable)}catch(i){throw new Error(`Can't add "${a.name}" to ${e}: row ${t.fileName} already holds a value for it that doesn't fit (${i.message})`)}const o=r.filter((e=>!has(e.data,a.name))),n=has(a,"default");if(o.length&&!a.optional&&!n&&!a.autoGenerate)throw new Error(`Can't add required field "${a.name}" to ${e}: its ${o.length} row(s) have no value for it (give it a default, or make it optional)`);return await writeRecord(e,i),a.autoGenerate?await setField(e,i,o,a.name,(()=>crypto.randomUUID())):n&&await setField(e,i,o,a.name,a.default),i},dropField=async(e,t,a)=>{(0,_knownFields.assertFieldsDefined)(e,t,[a],"alter");const i=keysUsing(t,a)[0];if(i)throw new Error(`Can't drop "${a}" from ${e}: its ${describeKey(i)} uses it`);const r=(await referencesTo(e,a))[0];if(r)throw new Error(`Can't drop "${a}" from ${e}: ${r.entity}'s foreign key "${r.key.fields[0]}" references it`);const o={...t,definition:t.definition.filter((e=>e.name!==a))};return await writeRecord(e,o),await setField(e,o,(await rowsOf(t)).filter((e=>has(e.data,a))),a,void 0),o},renameField=async(e,t,a,i)=>{if((0,_knownFields.assertFieldsDefined)(e,t,[a],"alter"),t.definition.some((e=>e.name===i)))throw new Error(`Can't rename "${a}" on ${e} to "${i}": a field of that name already exists`);const r=await referencesTo(e,a),o=t.keys.map((e=>{if(!e.fields.includes(a))return e;const t=e.fields.map((e=>e===a?i:e)),r=e.lookup&&e.lookup===(0,_parseCreate.keyLookup)(e.type,e.fields)?(0,_parseCreate.keyLookup)(e.type,t):e.lookup;return{...e,fields:t,lookup:r}})),n=t=>"foreign"!==t.type?t:{...t,references:(t.references||[]).map((t=>({...t,fields:t.fields.map((t=>t===`${e}.${a}`?`${e}.${i}`:t))})))},s={...t,definition:t.definition.map((e=>e.name===a?{...e,name:i}:e)),keys:o.map(n)};for(const[e,a]of t.keys.entries()){const i=o[e].lookup;a.lookup&&i!==a.lookup&&(0,_storage.fileExists)(`__indexes/${t.path}/${a.lookup}`)&&(await(0,_storage.writeJson)(`__indexes/${t.path}/${i}`,await(0,_storage.readJson)(`__indexes/${t.path}/${a.lookup}`)),await(0,_storage.removeFile)(`__indexes/${t.path}/${a.lookup}`))}await writeRecord(e,s);for(const t of r.filter((t=>t.entity!==e)))await(0,_storage.writeJson)(`${t.entity}.json`,{...t.record,keys:t.record.keys.map(n)});const d=(await rowsOf(t)).filter((e=>has(e.data,a)));d.length&&await(0,_packedTable.discardPacked)(t.path);for(const e of d){const r=Object.assign({},e.data);r[i]=r[a],delete r[a],await(0,_storage.writeJson)(`${t.path}/${e.fileName}`,r)}return s},modifyField=async(e,t,a)=>{(0,_knownFields.assertFieldsDefined)(e,t,[a.name],"alter");const i=t.definition.find((e=>e.name===a.name));if(i.type!==a.type)throw new Error(`Can't change the type of "${a.name}" on ${e} (${i.type} to ${a.type}): only optional, null and default can change`);if(Boolean(i.autoGenerate)!==Boolean(a.autoGenerate))throw new Error(`Can't change whether "${a.name}" on ${e} is auto: only optional, null and default can change`);const r={...t,definition:t.definition.map((e=>e.name===a.name?a:e))},o=await rowsOf(t),n=has(a,"default"),s=a.nullable?[]:o.filter((e=>null===e.data[a.name])),d=a.optional?[]:o.filter((e=>!has(e.data,a.name))),l=a.optional?[]:s;if((d.length||l.length)&&!n)throw d.length?new Error(`Can't make "${a.name}" required on ${e}: ${d.length} row(s) have no value for it (give it a default to fill them in)`):new Error(`Can't make "${a.name}" not null on ${e}: ${l.length} row(s) hold null (give it a default to fill them in, or make it optional)`);return await writeRecord(e,r),n&&await setField(e,r,[...d,...l],a.name,a.default),a.optional&&s.length&&await setField(e,r,s,a.name,void 0),r},alter=async(e,t)=>{if((0,_requireNode.requireNode)("alter"),"__RECORDS"===e)throw new Error("__RECORDS is reserved for the list of records");[e,..."field"in t?[t.field?.name]:[],..."name"in t?[t.name]:[],..."to"in t?[t.to]:[]].forEach((e=>(0,_assertValidName.assertValidName)(e,"alter")));const a=await(0,_retrieveRecord.retrieveRecord)(e);switch(t.action){case"add":return(await addField(e,a,(0,_field.field)(t.field))).definition;case"drop":return(await dropField(e,a,t.name)).definition;case"rename":return(await renameField(e,a,t.name,t.to)).definition;case"modify":return(await modifyField(e,a,(0,_field.field)(t.field))).definition;default:throw new Error(`Unknown alter action: ${t.action}`)}};exports.alter=alter;

package/dist/data/introspect/create.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.create = exports.assertValidDefinition = void 0;
 require("core-js/modules/es.array.includes.js");
+var _assertValidName = require("../utilities/assertValidName");
 var _record = require("./definitions/record");
 var _registerRecord = require("../utilities/registerRecord");
 var _storage = require("../storage");
@@ -80,6 +81,20 @@ const create = async (recordName, definition = [], keys = []) => {
   if (recordName === '__RECORDS') {
     return null;
   }
+  // Names become file paths and row keys: refuse what the query language would (e.g. `../x` from a direct call)
+  (0, _assertValidName.assertValidName)(recordName, 'create()');
+  for (const field of definition) {
+    (0, _assertValidName.assertValidName)(field?.name, `create() of ${recordName}`);
+  }
+  for (const key of keys) {
+    (key?.fields ?? []).forEach(name => (0, _assertValidName.assertValidName)(name, `create() of ${recordName}`));
+    (0, _assertValidName.assertValidLookup)(key?.lookup, `create() of ${recordName}`);
+    for (const reference of key?.references ?? []) {
+      // A reference names the other record's file (`people.json`) and its fields as `people._id`
+      (0, _assertValidName.assertValidLookup)(reference?.lookup ?? null, `create() of ${recordName}`);
+      (reference?.fields ?? []).forEach(name => String(name).split('.').forEach(part => (0, _assertValidName.assertValidName)(part, `create() of ${recordName}`)));
+    }
+  }
   if ((0, _storage.fileExists)(`${recordName}.json`)) {
     return null;
   }

package/dist/data/introspect/create.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.create=exports.assertValidDefinition=void 0,require("core-js/modules/es.array.includes.js");var _record=require("./definitions/record"),_registerRecord=require("../utilities/registerRecord"),_storage=require("../storage"),_requireNode=require("../utilities/requireNode"),_typeCheck=require("./policies/typeCheck");const knownKeyProperties=["type","fields","lookup","references"],assertKnownKeyProperties=(e,r)=>{for(const o of r)for(const r of Object.keys(o))if(!knownKeyProperties.includes(r))throw new Error(`Unknown property "${r}" on ${o.type??"index"} key of ${e}; must be ${knownKeyProperties.join(", ")}`)},assertValidDefinition=(e,r)=>{for(const o of r.definition)if(Object.prototype.hasOwnProperty.call(o,"default"))try{(0,_typeCheck.typeCheck)(o.type,o.default,o.nullable)}catch(r){throw new Error(`Invalid default for field "${o.name}" of ${e}: ${r.message}`)}for(const o of r.keys){if(o.fields.length<1)throw new Error(`The ${o.type} key of ${e} must have at least one field`);for(const t of o.fields)if(!r.definition.some((e=>e.name===t)))throw new Error(`The ${o.type} key of ${e} names field "${t}", which isn't in the definition`)}const o=r.keys.find((e=>"primary"===e.type));for(const t of o?o.fields:[]){const o=r.definition.find((e=>e.name===t));if(o&&o.nullable)throw new Error(`Primary key field "${t}" of ${e} can't be nullable`);if(o&&o.optional&&!o.autoGenerate)throw new Error(`Primary key field "${t}" of ${e} can't be optional`)}};exports.assertValidDefinition=assertValidDefinition;const create=async(e,r=[],o=[])=>{if((0,_requireNode.requireNode)("create()"),"__RECORDS"===e)return null;if((0,_storage.fileExists)(`${e}.json`))return null;assertKnownKeyProperties(e,o);const t=(0,_record.record)({path:e,definition:r,keys:o});assertValidDefinition(e,t),await(0,_storage.makeDirectory)(),await(0,_storage.writeJson)(`${e}.json`,t),await(0,_storage.makeDirectory)(e);const i=t.keys.filter((e=>e.lookup));if(i.length){await(0,_storage.makeDirectory)(`__indexes/${e}`);for(const r of i)await(0,_storage.writeJson)(`__indexes/${e}/${r.lookup}`,[])}return await(0,_registerRecord.registerRecord)(e),t};exports.create=create;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.create=exports.assertValidDefinition=void 0,require("core-js/modules/es.array.includes.js");var _assertValidName=require("../utilities/assertValidName"),_record=require("./definitions/record"),_registerRecord=require("../utilities/registerRecord"),_storage=require("../storage"),_requireNode=require("../utilities/requireNode"),_typeCheck=require("./policies/typeCheck");const knownKeyProperties=["type","fields","lookup","references"],assertKnownKeyProperties=(e,r)=>{for(const t of r)for(const r of Object.keys(t))if(!knownKeyProperties.includes(r))throw new Error(`Unknown property "${r}" on ${t.type??"index"} key of ${e}; must be ${knownKeyProperties.join(", ")}`)},assertValidDefinition=(e,r)=>{for(const t of r.definition)if(Object.prototype.hasOwnProperty.call(t,"default"))try{(0,_typeCheck.typeCheck)(t.type,t.default,t.nullable)}catch(r){throw new Error(`Invalid default for field "${t.name}" of ${e}: ${r.message}`)}for(const t of r.keys){if(t.fields.length<1)throw new Error(`The ${t.type} key of ${e} must have at least one field`);for(const o of t.fields)if(!r.definition.some((e=>e.name===o)))throw new Error(`The ${t.type} key of ${e} names field "${o}", which isn't in the definition`)}const t=r.keys.find((e=>"primary"===e.type));for(const o of t?t.fields:[]){const t=r.definition.find((e=>e.name===o));if(t&&t.nullable)throw new Error(`Primary key field "${o}" of ${e} can't be nullable`);if(t&&t.optional&&!t.autoGenerate)throw new Error(`Primary key field "${o}" of ${e} can't be optional`)}};exports.assertValidDefinition=assertValidDefinition;const create=async(e,r=[],t=[])=>{if((0,_requireNode.requireNode)("create()"),"__RECORDS"===e)return null;(0,_assertValidName.assertValidName)(e,"create()");for(const t of r)(0,_assertValidName.assertValidName)(t?.name,`create() of ${e}`);for(const r of t){(r?.fields??[]).forEach((r=>(0,_assertValidName.assertValidName)(r,`create() of ${e}`))),(0,_assertValidName.assertValidLookup)(r?.lookup,`create() of ${e}`);for(const t of r?.references??[])(0,_assertValidName.assertValidLookup)(t?.lookup??null,`create() of ${e}`),(t?.fields??[]).forEach((r=>String(r).split(".").forEach((r=>(0,_assertValidName.assertValidName)(r,`create() of ${e}`)))))}if((0,_storage.fileExists)(`${e}.json`))return null;assertKnownKeyProperties(e,t);const o=(0,_record.record)({path:e,definition:r,keys:t});assertValidDefinition(e,o),await(0,_storage.makeDirectory)(),await(0,_storage.writeJson)(`${e}.json`,o),await(0,_storage.makeDirectory)(e);const i=o.keys.filter((e=>e.lookup));if(i.length){await(0,_storage.makeDirectory)(`__indexes/${e}`);for(const r of i)await(0,_storage.writeJson)(`__indexes/${e}/${r.lookup}`,[])}return await(0,_registerRecord.registerRecord)(e),o};exports.create=create;

package/dist/data/introspect/describe.js

@@ -5,7 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.describe = void 0;
 var _retrieveFile = require("../utilities/retrieveFile");
+var _assertValidName = require("../utilities/assertValidName");
 const describe = async (record = '__RECORDS') => {
+  (0, _assertValidName.assertValidName)(record, 'describe()');
   const recordFile = await (0, _retrieveFile.retrieveFile)(`${record}.json`);
   if (record === '__RECORDS') {
     return recordFile.entries;

package/dist/data/introspect/describe.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.describe=void 0;var _retrieveFile=require("../utilities/retrieveFile");const describe=async(e="__RECORDS")=>{const i=await(0,_retrieveFile.retrieveFile)(`${e}.json`);return"__RECORDS"===e?i.entries:i.definition};exports.describe=describe;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.describe=void 0;var _retrieveFile=require("../utilities/retrieveFile"),_assertValidName=require("../utilities/assertValidName");const describe=async(e="__RECORDS")=>{(0,_assertValidName.assertValidName)(e,"describe()");const i=await(0,_retrieveFile.retrieveFile)(`${e}.json`);return"__RECORDS"===e?i.entries:i.definition};exports.describe=describe;

package/dist/data/introspect/drop.js

@@ -9,11 +9,14 @@ var _deregisterRecord = require("../utilities/deregisterRecord");
 var _requireNode = require("../utilities/requireNode");
 var _storage = require("../storage");
 var _packedTable = require("../utilities/packedTable");
+var _assertValidName = require("../utilities/assertValidName");
 const drop = async record => {
   (0, _requireNode.requireNode)('drop()');
   if (record === '__RECORDS') {
     return null;
   }
+  // drop() removes files: a name like `../x` from a direct call must never reach storage
+  (0, _assertValidName.assertValidName)(record, 'drop()');
   const recordFile = await (0, _retrieveFile.retrieveFile)(`${record}.json`);
   for (const file of recordFile.entries) {
     await (0, _storage.removeFile)(`${recordFile.path}/${file}`);

package/dist/data/introspect/drop.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.drop=void 0;var _retrieveFile=require("../utilities/retrieveFile"),_deregisterRecord=require("../utilities/deregisterRecord"),_requireNode=require("../utilities/requireNode"),_storage=require("../storage"),_packedTable=require("../utilities/packedTable");const drop=async e=>{if((0,_requireNode.requireNode)("drop()"),"__RECORDS"===e)return null;const r=await(0,_retrieveFile.retrieveFile)(`${e}.json`);for(const e of r.entries)await(0,_storage.removeFile)(`${r.path}/${e}`);await(0,_storage.removeDirectory)(r.path),await(0,_storage.removeDirectory)(`__indexes/${r.path}`),await(0,_packedTable.discardPacked)(r.path),await(0,_storage.removeFile)(`${e}.json`),await(0,_deregisterRecord.deregisterRecord)(e)};exports.drop=drop;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.drop=void 0;var _retrieveFile=require("../utilities/retrieveFile"),_deregisterRecord=require("../utilities/deregisterRecord"),_requireNode=require("../utilities/requireNode"),_storage=require("../storage"),_packedTable=require("../utilities/packedTable"),_assertValidName=require("../utilities/assertValidName");const drop=async e=>{if((0,_requireNode.requireNode)("drop()"),"__RECORDS"===e)return null;(0,_assertValidName.assertValidName)(e,"drop()");const r=await(0,_retrieveFile.retrieveFile)(`${e}.json`);for(const e of r.entries)await(0,_storage.removeFile)(`${r.path}/${e}`);await(0,_storage.removeDirectory)(r.path),await(0,_storage.removeDirectory)(`__indexes/${r.path}`),await(0,_packedTable.discardPacked)(r.path),await(0,_storage.removeFile)(`${e}.json`),await(0,_deregisterRecord.deregisterRecord)(e)};exports.drop=drop;

package/dist/data/utilities/assertValidName.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Throw unless this is a name the query language allows (letters, digits, `_` and `-`). Record and field names end up
+ * in file paths and row keys, so a name like `../x` from a direct JS call must be refused before it reaches storage.
+ * @param name
+ * @param where What is being named, for the error (e.g. `create()`).
+ */
+export declare const assertValidName: (name: unknown, where: string) => void;
+/**
+ * Throw unless this is a valid index file name (`<name>.json`); an empty lookup (no index file) is allowed.
+ * @param lookup
+ * @param where
+ */
+export declare const assertValidLookup: (lookup: unknown, where: string) => void;
+//# sourceMappingURL=assertValidName.d.ts.map

package/dist/data/utilities/assertValidName.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.assertValidName = exports.assertValidLookup = void 0;
+require("core-js/modules/es.json.stringify.js");
+var _parseCreate = require("./parsers/parseCreate");
+/** An index file name: a name plus `.json`, as keyLookup makes them (e.g. `pk__id.json`). */
+const lookupMatch = /^[a-z0-9_-]+\.json$/i;
+/**
+ * Throw unless this is a name the query language allows (letters, digits, `_` and `-`). Record and field names end up
+ * in file paths and row keys, so a name like `../x` from a direct JS call must be refused before it reaches storage.
+ * @param name
+ * @param where What is being named, for the error (e.g. `create()`).
+ */
+const assertValidName = (name, where) => {
+  if (typeof name !== 'string' || !_parseCreate.nameMatch.test(name)) {
+    throw new Error(`Invalid name ${JSON.stringify(name) ?? 'undefined'} in ${where}: names use letters, digits, _ and - only`);
+  }
+};
+/**
+ * Throw unless this is a valid index file name (`<name>.json`); an empty lookup (no index file) is allowed.
+ * @param lookup
+ * @param where
+ */
+exports.assertValidName = assertValidName;
+const assertValidLookup = (lookup, where) => {
+  if (lookup === '' || typeof lookup === 'undefined') return;
+  if (typeof lookup !== 'string' || !lookupMatch.test(lookup)) {
+    throw new Error(`Invalid index file ${JSON.stringify(lookup) ?? 'undefined'} in ${where}: use a name plus .json`);
+  }
+};
+exports.assertValidLookup = assertValidLookup;

package/dist/data/utilities/assertValidName.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.assertValidName=exports.assertValidLookup=void 0,require("core-js/modules/es.json.stringify.js");var _parseCreate=require("./parsers/parseCreate");const lookupMatch=/^[a-z0-9_-]+\.json$/i,assertValidName=(e,s)=>{if("string"!=typeof e||!_parseCreate.nameMatch.test(e))throw new Error(`Invalid name ${JSON.stringify(e)??"undefined"} in ${s}: names use letters, digits, _ and - only`)};exports.assertValidName=assertValidName;const assertValidLookup=(e,s)=>{if(""!==e&&void 0!==e&&("string"!=typeof e||!lookupMatch.test(e)))throw new Error(`Invalid index file ${JSON.stringify(e)??"undefined"} in ${s}: use a name plus .json`)};exports.assertValidLookup=assertValidLookup;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-fs-query",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "A git-native JSON data store for static sites: JSON files with a schema, enforced keys and a SQL-like query language, read straight from static hosting.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,10 @@
     "prepublishOnly": "npm run build",
     "benchmark": "node scripts/benchmark.cjs"
   },
+  "bin": {
+    "json-fs-query": "dist/cli/index.js",
+    "jfsq": "dist/cli/index.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jheagle/json-fs-query.git"
@@ -49,6 +53,7 @@
   "homepage": "https://github.com/jheagle/json-fs-query#readme",
   "devDependencies": {
     "@babel/core": "^8.1.0",
+    "@types/node": "^26.6.5",
     "gulp": "^5.0.1",
     "js-build-tools": "^8.2.0",
     "playwright": "^1.65.0",
@@ -58,6 +63,7 @@
   },
   "dependencies": {
     "browser-or-node": "^3.0.0",
+    "commander": "^14.0.3",
     "core-js": "^3.51.0",
     "si-funciona": "^2.10.0"
   },