void 0.1.6 → 0.7.0

package/skills/void/docs/reference/structure.md

@@ -0,0 +1,176 @@
+---
+outline: deep
+---
+
+<script setup>
+const items = [
+  { name: "routes/", description: "API endpoints (file-based routing)", link: "#routes" },
+  { name: "pages/", description: "Full-stack server-rendered pages", link: "#pages" },
+  { name: "middleware/", description: "Global request middleware", link: "#middleware" },
+  { name: "db/", description: "Drizzle schema and SQL migrations", link: "#db" },
+  { name: "crons/", description: "Scheduled cron jobs", link: "#crons" },
+  { name: "queues/", description: "Async queue consumers", link: "#queues" },
+  { name: "src/", description: "Shared app code", link: "#src" },
+  { name: "public/", description: "Static assets (served as-is)", link: "#public" },
+  { name: ".void/", description: "Auto-generated (gitignored)", link: "#void" },
+  { name: "vite.config.ts", description: "Vite config with voidPlugin()", link: "#config-files" },
+  { name: "void.json", description: "Void project config (optional)", link: "#config-files" },
+  { name: ".env", description: "Environment variables", link: "#config-files" },
+  { name: "package.json" },
+  { name: "tsconfig.json" },
+];
+
+const middlewareItems = [
+  {
+    name: "middleware/",
+    children: [
+      { name: "01.logger.ts", description: "Runs first" },
+      { name: "02.auth.ts", description: "Runs second" },
+    ],
+  },
+];
+
+const dbItems = [
+  {
+    name: "db/",
+    children: [
+      { name: "schema.ts", description: "Drizzle schema (source of truth)" },
+      { name: "schema/", description: "Optional: split into multiple files" },
+      {
+        name: "migrations/",
+        children: [
+          { name: "20260410161500_*.sql" },
+          { name: "20260410161501_*.sql" },
+        ],
+      },
+    ],
+  },
+];
+
+const voidItems = [
+  {
+    name: ".void/",
+    children: [
+      { name: "db.d.ts", description: "Drizzle DB instance types" },
+      { name: "routes.d.ts", description: "Typed fetch client types" },
+      { name: "queues.d.ts", description: "Queue consumer types" },
+      { name: "tsconfig.json", description: "TypeScript config fragment" },
+      { name: "v3/", description: "Local dev state (D1, KV, R2)" },
+    ],
+  },
+];
+</script>
+
+# Project Structure
+
+## Overview
+
+A Void app uses file-based conventions to define routes, pages, middleware, and more. All directories are optional, so you only need the pieces your app actually uses.
+
+<FileTree :items="items" />
+
+## `routes/`
+
+File-based HTTP API endpoints built on [Hono](https://hono.dev). Each file exports named HTTP method handlers.
+
+<RoutesFileTree />
+
+- **Named exports**: `export const GET = defineHandler(...)`, `export const POST = ...`
+- **Dynamic segments**: `[id]` becomes `:id` route parameter
+- **Catch-all**: `[...slug]` matches the remaining path
+- **Route groups**: `(admin)/` organizes files without affecting URL paths
+- **Files starting with `_`** are ignored
+
+See [Server Routing](/guide/server-routing) for the full guide.
+
+## `pages/`
+
+Full-stack server-rendered pages with co-located data loading. Available with Vue, React, Svelte, and Solid adapters.
+
+<PagesFileTree />
+
+- **`.server.ts` files** export `loader` for `GET` data and `action` for mutations, paired with the page component of the same name
+- **Layouts** nest automatically and persist across navigations
+- **Markdown** pages are supported with frontmatter
+
+See [Pages Routing](/guide/pages-routing/overview) for the full guide.
+
+## `middleware/`
+
+Global middleware that runs on every request. Numeric prefixes control execution order.
+
+<FileTree :items="middlewareItems" default-expanded />
+
+Each file exports a `defineMiddleware()` handler. Use middleware to set shared context (auth, logging, rate limiting) available to all routes.
+
+## `db/`
+
+[Drizzle schema](/guide/database#schema-definition) and SQL migration files for the [D1 database](/guide/database).
+
+<FileTree :items="dbItems" default-expanded />
+
+- `db/schema.ts`: your Drizzle table definitions and the source of truth for DB types
+- `db/schema/`: optional. Split tables into separate files and re-export them from `db/schema.ts`
+- `db/migrations/`: generated SQL migration files, applied in order on deploy
+
+Generate schema with `void gen model` or write it by hand. Generate migrations with `void db generate`.
+
+## `crons/`
+
+[Scheduled jobs](/guide/jobs) that run on a cron schedule.
+
+```ts
+// crons/heartbeat.ts
+import { defineScheduled } from 'void';
+
+export const cron = '*/5 * * * *';
+
+export default defineScheduled(async (controller, env) => {
+  // runs every 5 minutes
+});
+```
+
+## `queues/`
+
+[Async queue consumers](/guide/queues) for background job processing.
+
+```ts
+// queues/email.ts
+import { defineQueue } from 'void';
+
+export default defineQueue(async (batch, env) => {
+  for (const msg of batch.messages) {
+    // process message
+  }
+});
+```
+
+## `src/`
+
+Shared application code such as components, utilities, and types. This directory has no special convention, so organize it however you like.
+
+## `public/`
+
+Static assets served as-is at the root path. Files here are not processed by Vite.
+
+## `.void/`
+
+Auto-generated directory (gitignored). Contains:
+
+Generate or refresh it with `void prepare`, or let `vite dev` / `vite build` populate it during normal app workflows.
+
+<FileTree :items="voidItems" default-expanded />
+
+## Config Files
+
+| File                    | Purpose                                                                                                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vite.config.ts`        | Vite configuration. Must include `voidPlugin()`.                                                                                                         |
+| `void.json`             | Optional Void config for [routing](/reference/config#routing), [inference](/reference/config#inference), and [worker settings](/reference/config#worker) |
+| `tsconfig.json`         | TypeScript config. Extend `.void/tsconfig.json` for auto-generated types; run `void init --tsconfig` when an existing config already uses `extends`.     |
+| `.env`                  | Public environment variables (committed)                                                                                                                 |
+| `.env.local`            | Secret variables for local dev (gitignored)                                                                                                              |
+| `.env.production`       | Public production variables (committed)                                                                                                                  |
+| `.env.production.local` | Production secrets for local testing (gitignored)                                                                                                        |
+
+See [Environment Variables](/guide/env-vars) for the full env file loading order.

package/.npmignore

@@ -1,29 +0,0 @@
-# Logs
-logs
-*.log
-
-# Runtime data
-pids
-*.pid
-*.seed
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Compiled binary addons (http://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directory
-# Deployed apps should consider commenting this line out:
-# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
-node_modules
-
-.DS_Store
-
-.env

package/.travis.yml

@@ -1,9 +0,0 @@
-language: node_js
-node_js:
-- '0.11'
-- '0.10'
-env:
-  global:
-  - secure: xGFuq3RAytMDckBZg+U+sX7ewyKdrDMEhAXoVZovhXdygmAmT9kEQksQHYPHUwYNpsCYQPNHa9aFOZ6JUgWlcFU3l425YEP8QTlkcchIlbWSCbpa2GTfqUR+e2kPbnvYhbcT0cX0D6WAa1+QUn9rQNXOXHlLwCF1vzlu4XO+n7Y=
-  - secure: olCdl0Ykg77MN/SXDqe31C34LcbjWrQD73AUuMs7syEFg0ixsoJJSSNKw81X3cF8geS3RwensrirNHsZFpwp1VAy+yPelvaaXhyXUn0aCj2ObRE544Yj5rLSw2MS+vLBtxPwbizLsD0fe90K4geOhZyj2fFbcz1olUWzVWfnyHI=
-  - secure: t/d2ATp/6Xgx0Js081HdDpiHn7+g7699lrLhljFEZRxBDK2FQOmr3U3ejdsGfut2hA24+8ub/RZgVmuCfbqbpeMZHSqmaBFRz7SEdd3syfCqYBeAQnZe+XwEKsKmsZxUvgOex3sXmrkGi4xZSIfrANabojjEP/msg/p/ZLeEfus=

package/index.js

@@ -1,14 +0,0 @@
-var AWS = require('aws-sdk'),
-	Void = require('./lib/Void.js');
-	Job = require('./lib/Job.js');
-
-var v = new Void({
-	paths : [
-		'/index.html',
-		'/index2.html',
-		'/foo/bar.html',
-		'/foo2/bar2.html'
-	],
-	maxPaths : 1,
-	maxJobs : 3
-});

package/lib/Job.js

@@ -1,150 +0,0 @@
-// External dependencies
-var AWS = require('aws-sdk'),
-	extend = require('jquery-extend');
-
-
-// Constructor
-var Job = function( options ) {
-
-	// Defaults
-	var defaults = {
-		name   : Math.random().toString(36).substr(2, 5).toUpperCase(), // Random name for logging, can be overridden
-		prefix : '', // Optional prefix for logging
-		id     : '', // Assigned by CloudFront
-		paths  : [], // Array of paths
-		status : 'paused', // Status string, one of 'paused', 'running', 'complete'
-		cloudfront     : new AWS.CloudFront(), // Credentialed AWS-SDK object
-		distribution   : process.env.DISTRIBUTION_ID,
-		running   : null, // Timestamp when the job started running
-		checking  : null, // Timestamp when the invalidation was created
-		createInterval : 2, // Minutes to wait before retrying to create an `Invalidation`
-		createTimeout  : 30, // Minutes to wait after 'running' status to quit trying to create an invalidation
-		checkDelay     : 10, // Minutes to wait before the first status check
-		checkInterval  : 2,  // Minutes to wait between 2nd-Nth status checks
-		checkTimeout   : 20, // Minutes to wait after the invalidation is created to quit and stop checking for progress
-		complete : null, // Optional callback to fire when invalidation completes
-		timeout  : null // Optional callback to fire when invalidation completes
-	};
-
-	// Extend `this` by our `defaults` and `options`
-	extend(true, this, defaults, options);
-
-	// Return this for chaining
-	return this;
-}
-
-
-// Run the job
-Job.prototype.run = function() {
-	this.status = 'running';
-	this.running = +new Date;
-	this.create();
-}
-
-
-// Attempt to create the invalidation
-Job.prototype.create = function() {
-
-	// See if we've timed out
-	if( (+new Date-this.running) > this.createTimeout * 60000 ) {
-		var message = 'Timeout: could not create invalidation after ' + this.createTimeout + ' minutes';
-		this.log(message);
-		if(typeof this.timeout == 'function') this.timeout(null, message, this);
-		return;
-	}
-
-	// Setup some data for the API
-	var params = {
-		DistributionId: this.distribution,
-		InvalidationBatch: {
-			CallerReference: this.name,
-			Paths: {
-				Quantity: this.paths.length,
-				Items: this.paths
-			}
-		}
-	};
-
-	// Send the request to AWS CloudFront
-	this.cloudfront.createInvalidation(params, function(err, data) {
-		if(err) {
-			if(err.code == 'TooManyInvalidationsInProgress') {
-				this.log('Too many invalidations, retrying in ' + this.createInterval + ' minute(s)');
-				setTimeout(this.create.bind(this), this.createInterval*60000);
-			} else {
-				this.log('Failed: ' + err.message);
-			}
-		} else {
-			this.id = data.Id;
-			this.log('Invalidation "' + this.id + '" created. Checking in ' + this.checkDelay + ' minute(s)...');
-			this.checking = +new Date;
-			setTimeout(this.check.bind(this), this.checkDelay*60000);
-		}
-	}.bind(this));
-}
-
-
-// Get the invalidation status from the API
-Job.prototype.check = function() {
-
-	// See if we've timed out
-	if( (+new Date-this.checking) > this.checkTimeout * 60000 ) {
-		var message = 'Timeout: stopped checking invalidation after ' + this.checkTimeout + ' minutes';
-		this.log(message);
-		if(typeof this.timeout == 'function') this.timeout(null, message, this);
-		return;
-	}
-
-	// Setup some data for the API
-	var params = {
-		DistributionId: this.distribution,
-		Id: this.id
-	};
-
-	// Send the request to AWS CloudFront
-	this.cloudfront.getInvalidation(params, function(err, data) {
-		if (err) {
-			this.log(err, err.stack);
-			this.complete(err);
-			return;
-	  	}
-
-	  	// Handle the status we get back
-  		switch( data.Status ) {
-  			case 'InProgress':
-		  		this.log('In progress, re-checking in ' + this.checkInterval + ' minute(s)...');
-				setTimeout(this.check.bind(this), this.checkInterval*60000);
-				return;
-  			case 'Completed':
-	  			this.status = 'complete';
-	  			var message = 'Invalidation "' + this.id + '" completed!';
-		  		this.log(message);
-		  		if(typeof this.complete == 'function') this.complete(null, message, this);
-		  		return;
-			default:
-	  			console.log(data); // something unexpected happened
-	  			return;
-		}
-
-	}.bind(this));
-}
-
-
-// Log labeled messages
-Job.prototype.log = function( message ) {
-	message = '[Job:' + this.name + '] ' + message;
-	if( this.prefix ) message = this.prefix + message;
-	console.log(message);
-}
-
-
-// Throw labeled errors
-Job.prototype.err = function( message ) {
-	message = '[Job:' + this.name + '] ' + message;
-	if( this.prefix ) message = this.prefix + message;
-	throw new Error(message);
-}
-
-
-// Export the constructor
-module.exports = Job;

package/lib/Void.js

@@ -1,99 +0,0 @@
-// External dependancies
-var AWS = require('aws-sdk'),
-	extend = require('jquery-extend'),
-	Job = require('./Job.js'),
-	scan = require('./scan.js');
-
-// Constructor
-var Void = function( options ) {
-
-	// Defaults
-	var defaults = {
-		name : Math.random().toString(36).substr(2, 5).toUpperCase(), // Random name for logging, can be overridden
-		distribution : process.env.DISTRIBUTION_ID, // AWS distribution id
-		paths    : [], // Paths to be cleared
-		dirs     : [], // Dirs to be scanned and added to `paths`
-		poison   : [], // Paths to be removed from `paths`
-		queue    : [], // Queue of invalidations
-		maxPaths : 2,  // Max number of paths per invalidation
-		maxJobs  : 3,  // Max number of simultaneous `Job` objects
-		cloudfront : new AWS.CloudFront() // Credentialed AWS-SDK object
-	};
-
-	// Extend `this` by our `defaults` and `options`
-	extend(true, this, defaults, options);
-
-	// Recurse `dirs` and add to `paths`
-	this.dirs.forEach(function(dir) {
-		var paths = scan(dir);
-		this.paths = this.paths.concat(paths)
-	}, this);
-
-	// Remove `poison` items from `paths`
-	this.poison.forEach(function(path) {
-		var i = this.paths.indexOf(path);
-		if( i > -1 ) this.paths.splice(i, 1);
-	}, this);
-
-	// Batch up paths into jobs and place them in the queue
-	this.populateQueue();
-
-	// Run the max number of jobs (or all jobs if fewer than max)
-	var max = ( this.queue.length < this.maxJobs ) ? this.queue.length : this.maxJobs;
-	for(i=0; i<max; i++) this.queue[i].run();
-
-};
-
-
-// Callback to loop over the queue and activate a job or notify when complete
-Void.prototype.runNextJob = function(err, data) {
-	if(err) this.err(err);
-
-	var counter = 0;
-	for(i=0; i<this.queue.length; i++) {
-		var job = this.queue[i];
-		if(job.status == 'paused') {
-			job.run();
-			return;
-		} else if(job.status == 'complete') {
-			counter++;
-		}
-	}
-	if( counter == this.queue.length ) this.log('All jobs complete!');
-};
-
-
-// Batch up our raw data into jobs and place them in the queue
-Void.prototype.populateQueue = function() {
-	var counter = 0;
-
-	for(i=0, j=this.paths.length; i<j; i+=this.maxPaths) {
-    	var subset = this.paths.slice(i, i+this.maxPaths);
-
-    	this.queue.push( new Job({
-    		prefix : '[Void:' + this.name + ']',
-    		paths : subset,
-    		complete : this.runNextJob.bind(this)
-    	}) );
-
-    	counter++;
-	}
-
-	this.log('Created ' + counter + ' item(s) in the queue');
-}
-
-
-// Log labeled messages
-Void.prototype.log = function( message ) {
-	console.log('[Void:' + this.name + '] ' + message);
-}
-
-
-// Throw labeled errors
-Void.prototype.err = function( message ) {
-	throw new Error('[Void:' + this.name + '] ' + message);
-}
-
-
-// Export the constructor
-module.exports = Void;

package/lib/scan.js

@@ -1,19 +0,0 @@
-// External dependancies
-var file = require('file');
-
-// Our helper function
-var scan = function( dir ) {
-
-	var path = process.cwd() + dir;
-	var arr = [];
-
-	file.walkSync(dir, function(dirPath, dirs, files) {
-		files.forEach(function(file) {
-			arr.push(dirPath.replace(dir, '') + '/' + file);
-		});
-	});
-
-	return arr;
-}
-
-module.exports = scan;

package/test/credentials.js

@@ -1,20 +0,0 @@
-// External dependancies
-var assert = require('assert'),
-	should = require('should');
-
-
-describe('AWS credentials', function() {
-
-	it('should throw an error if AWS_ACCESS_KEY_ID is undefined in the environment', function() {
-		assert.notEqual(process.env.AWS_ACCESS_KEY_ID, undefined);
-	});
-
-	it('should throw an error if AWS_SECRET_ACCESS_KEY is undefined in the environment', function() {
-		assert.notEqual(process.env.AWS_SECRET_ACCESS_KEY, undefined );
-	});
-
-	it('should throw an error if DISTRIBUTION_ID is undefined in the environment', function() {
-		assert.notEqual(process.env.DISTRIBUTION_ID, undefined );
-	});
-
-});

package/test/job.js

@@ -1,64 +0,0 @@
-// External dependancies
-var assert = require('assert'),
-	should = require('should'),
-	Job = require('../lib/Job.js'),
-	AWS = require('aws-sdk');
-
-
-// Constructor
-describe('Job', function() {
-
-	/* *
-	 * Validation
-	 */
-
-	it('should have a 5 character name property', function() {
-		var job =  new Job;
-		assert.equal(job.name.length, 5);
-	});
-
-	it('should have at least one path item', function() {
-		var job =  new Job({
-			paths : ['/index.html'],
-		});
-		assert.notEqual(job.paths.length, 0);
-	});
-
-
-	/* *
-	 * Timeouts
-	 */
-
-	/*it('should timeout while creating the invalidation', function(done) {
-		this.timeout(60000 * 20);
-		var job = new Job({
-			paths : [
-				'/index1.html',
-				'/index2.html',
-				'/index3.html',
-				'/index4.html'
-			],
-			createTimeout : 0.1,
-			createInterval : 0.1,
-			maxPaths : 1,
-			maxJobs : 4,
-			timeout : done
-		}).run();
-	});*/
-
-	/*it('should timeout while checking the invalidation', function(done) {
-		this.timeout(60000 * 20);
-		var job = new Job({
-			paths : ['/foo/bar.html'],
-			createInterval : 0.1,
-			checkTimeout : 0.1,
-			checkDelay : 0.1,
-			checkInterval : 0.1,
-			timeout : function() {
-				done();
-			}
-		});
-		job.run();
-	});*/
-
-});

package/test/void.js

@@ -1,31 +0,0 @@
-// External dependancies
-var assert = require('assert'),
-	should = require('should'),
-	Void = require('../lib/Void.js');
-
-
-// Constructor
-describe('Void', function() {
-
-	/* *
-	 * Queue building
-	 */
-
-	it('should have a queue of length 6', function() {
-		var v = new Void({
-			paths : ['/css/custom.css', '/index.html'],
-			dirs : ['test/static']
-		});
-		assert.equal(v.queue.length, 6);
-	});
-
-	it('should have a queue of length 5 because of the poison list', function() {
-		var v = new Void({
-			paths : ['/css/custom.css', '/index.html'],
-			dirs : ['test/static'],
-			poison : ['/test1.html', '/test2.html']
-		});
-		assert.equal(v.queue.length, 5);
-	});
-
-});