Definition File

Pocket Specs has to be given a "definition" file where ALL the various routes, event-handlers and utility functions are described. If you do not specify the definition file using the -def command-line argument, then it will try to load "default.do.txt" from the current working folder.

If you want you can keep such a definition file somewhere else; with a different extension also... and then use the -def command-line argument. But please note: The current working folder has special importance in Pocket Specs. All filenames are assumed to be from that folder (except pattern files; explained later)

Writing the definition file

The definition file has a specific syntax. This is NOT a JavaScript file. So when you load it into a text editor such as VS Code or VS Codium, do not switch on code-completion or syntax coloring. Treat it as a plain-jane text file.

Here is an example with which to understand this definition file. It is from the same sample project that you can download and use yourself. The project is for a simple CRUD SaaS application.

proj(["SreeChitra Ayurveda  -(c) Sabu Francis. Version 0.1","Simple CRUD sample"])
do(rpot("/api/v1/create/:coll"),"For creating a record in a collection",[],"create",[])
do(rget("/api/v1/readcount/:filt/:coll"),"For getting count of filtered records",[],"readcount",[])
do(rget("/api/v1/read/:filt/:sort/:limit/:offset/:coll"),"For reading a set of filtered and sorted records",[],"read",[])
do(rput("/api/v1/update/:recid/:coll"),"For updating a record in a collection as per record id",[],"update",[])
do(rdel("/api/v1/delete/:recid/:coll"),"For deleting a record in a collection as per record id ",[],"delete",[])

Each line in that defintion file represents one instruction. They look like JavaScript function calls. There are two types of instruction. The "proj(...)" instruction and the "do(...)" instruction. Project instruction

The proj(...) instruction is for declaring the project. There can ONLY be one such instruction and it must be the first instruction in that definition file for that project. The proj(...) instruction has just one "argument" -- a string list. The first string of this string list is usually a line that declares the name of the project ... In this case "SreeChitra Ayurveda" and maybe you can add a copyright notice too in the same first string. This is used inside a comment block at the top of every file generated by Pocket Specs for the project. I'll explain the rest of the members that may exist in that list later on in the appendix.

The "do" instruction

There would be multiple such "do(...)" instructions in the file; one per line. Each such instruction would eventually result in a file being generated. Each instruction is either for ONE route or for ONE event-handler or for ONE utility function. As there would be many routes/event-handlers/utility functions; it is quite likely that you would have multiple such "do(...)" instructions.

Again the do(...) instruction looks quite similar to a JavaScript function call. The first argument given to that do(...) instruction itself is a special sub-instruction, which I will explain later. The second argument is a comment that is used in the header of the file being generated. This is followed by one string list -- which could be empty. That depends on what is being generated. The fourth argument is a reference to a "chunk" instruction file. There is a separate chapter here on how to write those files. For now, remember that this argument is just the filename. The extension of such chunk instruction file is always ".chunk.js"

The last argument (fifth) is also a string list. Again explained later.

Arguments of each "do" instruction explained in detail...

The first argument of a "do" instruction. The first argument itself looks like a small JavaScript function call. There are seven possibilities for this sub-instruction as listed below:

1. utl(<String-Arg>)

2. rget(<URL-Arg>)

3. rpot(<URL-Arg>)

4. rput(<URL-Arg>)

5. rpch(<URL-Arg>)

6. rdel(<URL-Arg>)

7. evt(<eventHandlerArg>)

You can specify only one of those seven, per instruction. The sole argument that each one takes is written as a string (i.e. in quotation marks) In the example I gave above (for the "SreeChitra" Project) I have not used ALL the seven.

The utl(...) sub-instruction takes the name of a function that needs to be present in the exported object of utils.js Each of the r*(ARG) sub-instruction refers to each type of routes that may be needed in your Pocketbase project. In my example (SreeChitra) I have defined only routes, one of them is a "POST" http route, one of them is a "PUT" route, one of them is a "DEL" route and rest are "GET" routes.

As you may have guessed, the argument itself declares the route url to be used.

Let me use the first route to explain each of those arguments for the "do" instruction.

do(rpot("/api/v1/create/:coll"),"For creating a record in a collection",[],"create",[])

See the URL specified for the rpot(...) sub-instructions. You can see parameters being defined there. Pocket Specs extracts those parameters and gives you neat list of consts right at the top of the function body.

The second argument is a comment that is placed in the head of the file.

The third argument is a list of Query String variables. In case of some routes, you may expect that URL to carry a Query String; and Pocket Specs will convert those also into consts in your code.

The fourth argument is used ONLY for POST, PUT and PATCH http routes. This is a list of POST Body data. A reserved 'const' is automatically created for the 'data' object for such a "Body" using this line of code:

 const data =  $apis.requestInfo(c).data;

Often you may not have to specify the specific POST fields in the fourth argument, as you can access the fields by the dot operator on the data constant; such as data.username etc.

The fifth argument are incoming request headers. The headers would obviously be for only the route this argument belongs to.

The same name as the header fields gets magically converted to const names. But as header fields may have characters that are not accepted as a const/variable name in JavaScript; those are converted to underscore. So the "Content-type" header field would become "content_type"; as an example.

NOTE:

The 4th and 5th arguments which were present before version 0.601 is no longer available. So you don't have to specify post body data nor headers. Instead; at the appropriate routes, the following two consts are automatically made available in the generated source code.

const data =  $apis.requestInfo(c).data;
const headers = $apis.requestInfo(c).headers;

The fourth argument refer to the chunk file. Such a chunk file will further describes the actual code that would get developed. In the above example; it is "create" So Pocket Specs would look for a file named "create.chunk.js" ... and since you did not give any folder path for that; it will look for the file in the current working folder (i.e. the folder from where you started the build process using Pocket Specs) This argument is also later used to form the final JS file when Pocket Specs does its work: It will add the extension of .pb.js to the filename. Note that the final output is always in the build folder you had specified on the command-line using the -build argument. If that argument was not given, then the final .pb.js files are generated in the current working folder itself.

NOTE: All the utilities functions are gathered together as methods of one exported object from a file named "utils.js" (This does not have .pb.js extension. Just .js) So in case of the utl(...) sub-instruction, the fourth argument is ONLY for the respective .chunk.js file that Pocket Specs would use for forming the code for that specific utility function.

The fifth argument is again a list of strings. Each of the strings in this list is used as a "tag" that are sometimes needed in event-handlers ... and also for calling "middleware" functions in case of routes.