The Why ...and Concepts

I wrote this utility because I realized I was doing extensive coding with Pocketbase. I needed to be much more efficient with it. Pocketbase is an excellent system to quickly create a SaaS application. It is just one file! Though the author keeps emphasizing that it is still not reached version 1.0, it seems (to my amateur eye) that it is quite stable and one can easily use it. The documentation is also excellent. See https://pocketbase.io

Over time I wanted to reach the following goals when coding in Pocketbase

1. I wanted to reduce the actual code that I need to write manually.

2. I wanted to have a system which would let me first describe an app very pithily, and then keep improving incrementally. Kind of a Kaizen system. It allows for "top-down" development , where the holistic parts of my project are written down, and I can then get to the details as and when I want.

3. However, I also wanted to have a system that can do "bottom-up" work too -- which means, write and tweak the code at a deep level as per my requirement. It is like kneading dough. At one point you are pushing the dough by pressing top-down but you are also doing bottom-up movements too! Software writing (like many creative processes) are iterative (agile or "spiral") where you keep going over and over time and again. That's also how a potter spins a pot on a potters-wheel.

4. I wanted to have separation of concerns. That means, I need to have a "build" process for Pocketbase, where I can delegate parts of the work to different people in my office.

5. I want to capture common code-patterns and make a library (or "add-ons" if you prefer that term) for them. That way, I don't have to rewrite those parts of the code at all.

Fortunately, I was able to achieve all that in Pocket Specs! I can happily iterate on a project extremely fast. Pocket Specs is like an able assistant, that helps be write out the entire code and also does a good amount of house-keeping. It is extensible too -- you can keep adding separate "pattern" files for common coding algorithms you use. I use Pocket Specs for the entire code development of the server side code in Pocketbase but it can always be used partially too -- One can iterate to the point where Pocket Specs has developed sufficient code as per your definitions -- and the rest, you do manually. IMPORTANT However, in case you use Pocket Specs partially; then you must be aware that Pocket Specs would always overwrite the code it generates. So if you were to manually make changes to the generated code; Pocket Specs would erase all that in the next generation of your specs! In short; the moment you switch onto manual mode, shift the code developed till that point in time, into a new folder!

Concepts

A Pocketbase SaaS application (on the server side) has 3 kinds of code: One for the various routes you are developing for your SaaS app. The second would be for various event handlers that you want to place -- that captures events (before and after)... These two are well described in the Pocketbase documentation. Then there is a 3rd type of code you write -- which is for repetitive utility functions that you may use multiple times in various other parts of your code. In case of Pocket Specs those utility functions are gathered together into one file called utils.js This is a "module" which has ONE exported object -- and the functions defined in that object can be used multiple times in the rest of the code you develop.

In order to achieve those end-goals, Pocket Specs enforces a simple set of disciplined work.

Main Definition File Firstly, for the entire project you need to create a definition file. This is usually ending in the extension .do.txt (but you can use any file extension, frankly) This definition file uses a syntax I have invented and you MUST give the definitions for each route, each event handler and each utility function as per that syntax.

Once you have the definition file ready, it will be used by Pocket Specs to look for what I call as "chunk" files. Chunks Let me explain first what a "chunk" is -- it is the name I have given to one logical part of the body of a route or the body of an event handler or; in case of the utilities, a function that is exported and used in multiple places. Those chunks are written in files that necessarily have to have an extension of .chunk.js Such chunk files also have to be written in a disciplined manner (described later in this documentation) but those files follow the JS Syntax (with special comments that Pocket Specs understands) The reason is that you would be doing your coding in such chunk files, so that's best done in a code-editor that understands JavaScript (for auto-complete, etc.) Editors I have edited such chunk files in VS Codium, with the AI tool "codeium" that works inside VS Codium (and VS Code, I presume) ...and it works just fine. Which means, VS Codium would point out errors in the JS syntax quite well; and even help you with code completion too. In fact, I noticed that "codeium" even learns bits of the Pocket Specs workings and suggests useful code too! That's quite remarkable and commendable about that AI tool. Because it does that even though the JS you write in such chunk files is actually not conventional JS files. Then you run Pocket Specs by using its command-line arguments (described later). (ideally thru a build.bat batch file, so you don't have to keep re-typing the command all the time for each iteration) Pocket Specs will produce the required final code for all the parts it understood. It integrates your own code, along with the code it generates on its own, and it also picks up from pattern files; if you had specified those.

In case Pocket Specs did not understand a particular definition (or a particular chunk instruction) it will stop at that line. It will NOT act on any instruction after the offending line -- but the instructions earlier to the error may get worked upon! So the code generation would be partial. NOTE: Pocket Specs would try its level best to generate JS with the correct syntax. If; for some reason, the generated JS is not of the right syntax, the problem would be normally be found in the code you wrote in the chunk files.

Summary

The simplest way to understand what is going on in Pocket Specs is that it works by a series of redirections.

First, it picks up the instructions from the main definition file. Each instruction is used to craft the source code of one final JavaScript file (All of them have an extension of .pb.js; except for utils.js) Each instruction is like a JavaScript function call -- one of the duties of the instruction is to redirect attention to what is known as a "chunk" file. Each chunk file itself contains a set of instructions (the syntax of this is different from the main definition file). There will usually be multiple chunk instructions; each one for one specific chunk. Each of the instruction has a keyword which redirects Pocket Specs attention to a set of smaller pieces of code -- each of which is then processed by Pocket Specs in proper order. After all that redirection from top-down and processing the code; Pocket Specs will generate all the code properly. My experience tells me that Pocket Specs reduces the amount of code you write to approximately 50%