spooder 4.5.7 → 4.5.9

package/README.md

@@ -1215,6 +1215,16 @@ await parse_template('Hello {$world}', replacer);
 </html>
 ```
 
+`parse_template` supports optional scopes with the following syntax.
+
+```html
+{$if:foo}I love {$foo}{/if}
+```
+Contents contained inside an `if` block will be rendered providing the given value, in this case `foo` is truthy in the substitution table.
+
+An `if` block is only removed if `drop_missing` is `true`, allowing them to persist through multiple passes of a template.
+
+
 `parse_template` supports looping arrays with the following syntax.
 
 ```html
@@ -1540,7 +1550,28 @@ Each revision should be clearly marked with a comment containing the revision nu
 
 Everything following a revision header is considered part of that revision until the next revision header or the end of the file, allowing for multiple SQL statements to be included in a single revision.
 
-When calling `db_update_schema_sqlite`, unapplied revisions will be applied in ascending order (regardless of order within the file) until the schema is up-to-date. Schema revisions are tracked in a table called `db_schema` which is created automatically if it does not exist with the following schema.
+When calling `db_update_schema_sqlite`, unapplied revisions will be applied in ascending order (regardless of order within the file) until the schema is up-to-date.
+
+It is acceptable to omit keys. This can be useful to prevent repitition when managing stored procedures, views or functions.
+
+```sql
+-- example of repetitive declaration
+
+-- [1] create view
+CREATE VIEW `view_test` AS SELECT * FROM `table_a` WHERE col = 'foo';
+
+-- [2] change view
+DROP VIEW IF EXISTS `view_test`;
+CREATE VIEW `view_test` AS SELECT * FROM `table_b` WHERE col = 'foo';
+```
+Instead of unnecessarily including each full revision of a procedure, view or function in the schema file, simply store the most up-to-date one and increment the version.
+```sql
+-- [2] create view
+CREATE OR REPLACE VIEW `view_test` AS SELECT * FROM `table_b` WHERE col = 'foo';
+```
+
+
+Schema revisions are tracked in a table called `db_schema` which is created automatically if it does not exist with the following schema.
 
 ```sql
 CREATE TABLE db_schema (
@@ -1549,6 +1580,12 @@ CREATE TABLE db_schema (
 );
 ```
 
+The table used for schema tracking can be changed if necessary by providing an alternative table name as the third paramater.
+
+```ts
+await db_update_schema_sqlite(db, './schema', 'my_schema_table');
+```
+
 >[!IMPORTANT]
 > The entire process is transactional. If an error occurs during the application of **any** revision for **any** table, the entire process will be rolled back and the database will be left in the state it was before the update was attempted.
 
@@ -1565,6 +1602,20 @@ try {
 }
 ```
 
+### Schema Dependencies
+By default, schema files are executed in the order they are provided by the operating system (generally alphabetically).
+
+If you have a schema file that depends on one or more other schema files to be executed before it (for example, using foreign keys), you can specify dependencies.
+
+```sql
+-- [deps] table_b_schema.sql, table_c_schema.sql
+-- [1] create table_a
+CREATE ...
+```
+
+>[!IMPORTANT]
+> Cyclic or missing dependencies will throw an error.
+
 ## Legal
 This software is provided as-is with no warranty or guarantee. The authors of this project are not responsible or liable for any problems caused by using this software or any part thereof. Use of this software does not entitle you to any support or assistance from the authors of this project.
 

package/bun.lock

@@ -0,0 +1,51 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "spooder",
+      "devDependencies": {
+        "@types/bun": "^1.1.8",
+      },
+      "optionalDependencies": {
+        "mysql2": "^3.11.0",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.0", "", { "dependencies": { "bun-types": "1.2.0" } }, "sha512-5N1JqdahfpBlAv4wy6svEYcd/YfO2GNrbL95JOmFx8nkE6dbK4R0oSE5SpBA4vBRqgrOUAXF8Dpiz+gi7r80SA=="],
+
+    "@types/node": ["@types/node@22.10.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-Ir6hwgsKyNESl/gLOcEz3krR4CBGgliDqBQ2ma4wIhEx0w+xnoeTq3tdrNw15kU3SxogDjOgv9sqdtLW8mIHaw=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "aws-ssl-profiles": ["aws-ssl-profiles@1.1.2", "", {}, "sha512-NZKeq9AfyQvEeNlN0zSYAaWrmBffJh3IELMZfRpJVWgrpEbtEpnjvzqBPf+mxoI287JohRDoa+/nsfqqiZmF6g=="],
+
+    "bun-types": ["bun-types@1.2.0", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-KEaJxyZfbV/c4eyG0vyehDpYmBGreNiQbZIqvVHJwZ4BmeuWlNZ7EAzMN2Zcd7ailmS/tGVW0BgYbGf+lGEpWw=="],
+
+    "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
+
+    "generate-function": ["generate-function@2.3.1", "", { "dependencies": { "is-property": "^1.0.2" } }, "sha512-eeB5GfMNeevm/GRYq20ShmsaGcmI81kIX2K9XQx5miC8KdHaC6Jm0qQ8ZNeGOi7wYB8OsdxKs+Y2oVuTFuVwKQ=="],
+
+    "iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
+
+    "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
+
+    "long": ["long@5.2.4", "", {}, "sha512-qtzLbJE8hq7VabR3mISmVGtoXP8KGc2Z/AT8OuqlYD7JTR3oqrgwdjnk07wpj1twXxYmgDXgoKVWUG/fReSzHg=="],
+
+    "lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
+
+    "lru.min": ["lru.min@1.1.1", "", {}, "sha512-FbAj6lXil6t8z4z3j0E5mfRlPzxkySotzUHwRXjlpRh10vc6AI6WN62ehZj82VG7M20rqogJ0GLwar2Xa05a8Q=="],
+
+    "mysql2": ["mysql2@3.12.0", "", { "dependencies": { "aws-ssl-profiles": "^1.1.1", "denque": "^2.1.0", "generate-function": "^2.3.1", "iconv-lite": "^0.6.3", "long": "^5.2.1", "lru.min": "^1.0.0", "named-placeholders": "^1.1.3", "seq-queue": "^0.0.5", "sqlstring": "^2.3.2" } }, "sha512-C8fWhVysZoH63tJbX8d10IAoYCyXy4fdRFz2Ihrt9jtPILYynFEKUUzpp1U7qxzDc3tMbotvaBH+sl6bFnGZiw=="],
+
+    "named-placeholders": ["named-placeholders@1.1.3", "", { "dependencies": { "lru-cache": "^7.14.1" } }, "sha512-eLoBxg6wE/rZkJPhU/xRX1WTpkFEwDJEN96oxFrTsqBdbT5ec295Q+CoHrL9IT0DipqKhmGcaZmwOt8OON5x1w=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "seq-queue": ["seq-queue@0.0.5", "", {}, "sha512-hr3Wtp/GZIc/6DAGPDcV4/9WoZhjrkXsi5B/07QgX8tsdc6ilr7BFM6PM6rbdAX1kFSDYeZGLipIZZKyQP0O5Q=="],
+
+    "sqlstring": ["sqlstring@2.3.3", "", {}, "sha512-qC9iz2FlN7DQl3+wjwn3802RTyjCx7sDvfQEXchwa6CWOx07/WVfh91gBmQ9fahw8snwGEWU3xGzOt4tFyHLxg=="],
+
+    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.5.7",
+	"version": "4.5.9",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.ts

@@ -173,6 +173,25 @@ export async function parse_template(template: string, replacements: Replacement
 					}
 					i += loop_content.length + 6;
 				}
+			} else if (buffer.startsWith('if:')) {
+				const if_key = buffer.substring(3);
+				const if_content_start_index = i + 1;
+				const if_close_index = template.indexOf('{/if}', if_content_start_index);
+
+				if (if_close_index === -1) {
+					if (!drop_missing)
+						result += '{$' + buffer + '}';
+				} else {
+					const if_content = template.substring(if_content_start_index, if_close_index);
+					const condition_value = is_replacer_fn ? await replacements(if_key) : replacements[if_key];
+
+					if (!drop_missing) {
+						result += '{$' + buffer + '}' + if_content + '{/if}';
+					} else if (condition_value) {
+						result += await parse_template(if_content, replacements, drop_missing);
+					}
+					i += if_content.length + 5;
+				}
 			} else {
 				const replacement = is_replacer_fn ? await replacements(buffer) : replacements[buffer];
 				if (replacement !== undefined)
@@ -227,6 +246,46 @@ export async function generate_hash_subs(length = 7, prefix = 'hash=', hashes?:
 	return hash_map;
 }
 
+interface DependencyTarget {
+	file_name: string;
+	deps: string[];
+}
+
+function order_schema_dep_tree<T extends DependencyTarget>(deps: T[]): T[] {
+	const visited = new Set<string>();
+	const temp = new Set<string>();
+	const result: T[] = [];
+	const map = new Map(deps.map(d => [d.file_name, d]));
+ 
+	function visit(node: T): void {
+		if (temp.has(node.file_name))
+			throw new Error(`Cyclic dependency {${node.file_name}}`);
+ 
+		if (visited.has(node.file_name))
+			return;
+ 
+		temp.add(node.file_name);
+ 
+		for (const dep of node.deps) {
+			const dep_node = map.get(dep);
+			if (!dep_node)
+				throw new Error(`Missing dependency {${dep}}`);
+			
+			visit(dep_node as T);
+		}
+ 
+		temp.delete(node.file_name);
+		visited.add(node.file_name);
+		result.push(node);
+	}
+ 
+	for (const dep of deps)
+		if (!visited.has(dep.file_name))
+			visit(dep);
+ 
+	return result;
+ }
+
 type Row_DBSchema = { db_schema_table_name: string, db_schema_version: number };
 type SchemaVersionMap = Map<string, number>;
 
@@ -249,23 +308,31 @@ async function db_load_schema(schema_dir: string, schema_versions: SchemaVersion
 		const schema_path = path.join(schema_file_ent.parentPath, schema_file);
 		const schema = await fs.readFile(schema_path, 'utf8');
 
+		const deps = new Array<string>();
+
 		const revisions = new Map();
 		let current_rev_id = 0;
 		let current_rev = '';
 
 		for (const line of schema.split(/\r?\n/)) {
-			const rev_start = line.match(/^--\s*\[(\d+)\]/);
-			if (rev_start !== null) {
-				// New chunk definition detected, store the current chunk and start a new one.
-				if (current_rev_id > 0) {
-					revisions.set(current_rev_id, current_rev);
-					current_rev = '';
-				}
+			const line_identifier = line.match(/^--\s*\[(\d+|deps)\]/);
+			if (line_identifier !== null) {
+				if (line_identifier[1] === 'deps') {
+					// Line contains schema dependencies, example: -- [deps] schema_b.sql,schema_c.sql
+					const deps_raw = line.substring(line.indexOf('deps') + 4);
+					deps.push(...deps_raw.split(',').map(e => e.trim().toLowerCase()));
+				} else {
+					// New chunk definition detected, store the current chunk and start a new one.
+					if (current_rev_id > 0) {
+						revisions.set(current_rev_id, current_rev);
+						current_rev = '';
+					}
 
-				const rev_number = parseInt(rev_start[1]);
-				if (isNaN(rev_number) || rev_number < 1)
-					throw new Error(rev_number + ' is not a valid revision number in ' + schema_file_lower);
-				current_rev_id = rev_number;
+					const rev_number = parseInt(line_identifier[1]);
+					if (isNaN(rev_number) || rev_number < 1)
+						throw new Error(rev_number + ' is not a valid revision number in ' + schema_file_lower);
+					current_rev_id = rev_number;
+				}
 			} else {
 				// Append to existing revision.
 				current_rev += line + '\n';
@@ -281,35 +348,40 @@ async function db_load_schema(schema_dir: string, schema_versions: SchemaVersion
 			continue;
 		}
 
+		if (deps.length > 0)
+			log('[{db}] {%s} dependencies: %s', schema_file, deps.map(e => '{' + e +'}').join(', '));
+
 		const current_schema_version = schema_versions.get(schema_name) ?? 0;
 		schema_out.push({
 			revisions,
+			file_name: schema_file_lower,
 			name: schema_name,
 			current_version: current_schema_version,
+			deps,
 			chunk_keys: Array.from(revisions.keys()).filter(chunk_id => chunk_id > current_schema_version).sort((a, b) => a - b)
 		});
 	}
 
-	return schema_out;
+	return order_schema_dep_tree(schema_out);
 }
 
-export async function db_update_schema_sqlite(db: Database, schema_dir: string) {
+export async function db_update_schema_sqlite(db: Database, schema_dir: string, schema_table_name = 'db_schema') {
 	log('[{db}] updating database schema for {%s}', db.filename);
 
 	const schema_versions = new Map();
 
 	try {
-		const query = db.query('SELECT db_schema_table_name, db_schema_version FROM db_schema');
+		const query = db.query('SELECT db_schema_table_name, db_schema_version FROM ' + schema_table_name);
 		for (const row of query.all() as Array<Row_DBSchema>)
 			schema_versions.set(row.db_schema_table_name, row.db_schema_version);
 	} catch (e) {
-		log('[{db}] creating {db_schema} table');
-		db.run('CREATE TABLE db_schema (db_schema_table_name TEXT PRIMARY KEY, db_schema_version INTEGER)');
+		log('[{db}] creating {%s} table', schema_table_name);
+		db.run(`CREATE TABLE ${schema_table_name} (db_schema_table_name TEXT PRIMARY KEY, db_schema_version INTEGER)`);
 	}
 	
 	db.transaction(async () => {
 		const update_schema_query = db.prepare(`
-			INSERT INTO db_schema (db_schema_version, db_schema_table_name) VALUES (?1, ?2)
+			INSERT INTO ${schema_table_name} (db_schema_version, db_schema_table_name) VALUES (?1, ?2)
 			ON CONFLICT(db_schema_table_name) DO UPDATE SET db_schema_version = EXCLUDED.db_schema_version
 		`);
 
@@ -332,7 +404,7 @@ export async function db_update_schema_sqlite(db: Database, schema_dir: string)
 	})();
 }
 
-export async function db_update_schema_mysql(db: mysql_types.Connection, schema_dir: string) {
+export async function db_update_schema_mysql(db: mysql_types.Connection, schema_dir: string, schema_table_name = 'db_schema') {
 	if (mysql === undefined)
 		throw new Error('{db_update_schema_mysql} cannot be called without optional dependency {mysql2} installed');
 
@@ -341,18 +413,18 @@ export async function db_update_schema_mysql(db: mysql_types.Connection, schema_
 	const schema_versions = new Map();
 
 	try {
-		const [rows] = await db.query('SELECT db_schema_table_name, db_schema_version FROM db_schema');
+		const [rows] = await db.query('SELECT db_schema_table_name, db_schema_version FROM ' + schema_table_name);
 		for (const row of rows as Array<Row_DBSchema>)
 			schema_versions.set(row.db_schema_table_name, row.db_schema_version);
 	} catch (e) {
-		log('[{db}] creating {db_schema} table');
-		await db.query('CREATE TABLE db_schema (db_schema_table_name VARCHAR(255) PRIMARY KEY, db_schema_version INT)');
+		log('[{db}] creating {%s} table', schema_table_name);
+		await db.query(`CREATE TABLE ${schema_table_name} (db_schema_table_name VARCHAR(255) PRIMARY KEY, db_schema_version INT)`);
 	}
 
 	await db.beginTransaction();
 	
 	const update_schema_query = await db.prepare(`
-		INSERT INTO db_schema (db_schema_version, db_schema_table_name) VALUES (?, ?)
+		INSERT INTO ${schema_table_name} (db_schema_version, db_schema_table_name) VALUES (?, ?)
 		ON DUPLICATE KEY UPDATE db_schema_version = VALUES(db_schema_version);
 	`);
 
@@ -797,7 +869,7 @@ export function serve(port: number, hostname?: string) {
 		}
 	});
 
-	log('server started on port {%d}', port);
+	log('server started on port {%d} (host: {%s})', port, hostname ?? 'unspecified');
 
 	return {
 		/** Register a handler for a specific route. */