#665 Type generator + Typed Resources

browser/.eslintrc.cjs

@@ -31,8 +31,9 @@ module.exports = {
     tsconfigRootDir: __dirname,
     project: [
       'lib/tsconfig.json',
+      'cli/tsconfig.json',
       'react/tsconfig.json',
-      'data-browser/tsconfig.json',
+      'data-browser/tsconfig.json'
     ],
   },
   plugins: ['react', '@typescript-eslint', 'prettier', 'react-hooks', 'jsx-a11y'],

browser/cli/.gitignore

@@ -0,0 +1 @@
+/bin

browser/cli/package.json

@@ -0,0 +1,32 @@
+{
+  "version": "0.35.1",
+  "author": "Polle Pas",
+  "dependencies": {
+    "@tomic/lib": "^0.35.1",
+    "chalk": "^5.3.0",
+    "typescript": "^4.8"
+  },
+  "description": "",
+  "license": "MIT",
+  "name": "@tomic/cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint ./src --ext .js,.ts",
+    "lint-fix": "eslint ./src --ext .js,.ts --fix",
+    "prepublishOnly": "pnpm run build && pnpm run lint-fix",
+    "watch": "tsc --build --watch",
+    "start": "pnpm watch",
+    "tsc": "tsc --build",
+    "typecheck": "tsc --noEmit"
+  },
+  "bin": {
+    "ad-generate": "./bin/src/index.js"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@tomic/lib": "^0.35.1"
+  }
+}

browser/cli/readme.md

@@ -0,0 +1,161 @@
+# @tomic/cli
+
+@tomic/cli is a cli tool that helps the developer with creating a front-end for their atomic data project by providing typesafety on resources.
+
+In atomic data you can create [ontologies](https://atomicdata.dev/class/ontology) that describe your business model. Then you use this tool to generate Typscript types for these ontologies in your front-end.
+
+```typescript
+import { Post } from './ontolgies/blog'; // <--- generated
+
+const myBlogpost = await store.getResourceAsync<Post>(
+  'https://myblog.com/atomic-is-awesome',
+);
+
+const comments = myBlogpost.props.comments; // string[] automatically infered!
+```
+
+## Getting started
+
+### Installation
+
+You can install the package globally or as a dev dependancy of your project.
+
+**Globally**:
+
+```
+npm install -g @tomic/cli
+```
+
+**Dev Dependancy:**
+
+```
+npm install -D @tomic/cli
+```
+
+If you've installed it globally you can now run the `ad-generate` command in your command line.
+When installing as a dependancy your PATH won't know about the command and so you will have to make a script in your `package.json` and run it via `npm <script_name>` instead.
+
+```json
+"scripts": {
+	"generate": "ad-generate"
+}
+```
+
+### Generating the files
+
+To start generating your ontologies you first need to configure the cli. Start by creating the config file by running:
+
+```
+ad-generate init
+```
+
+There should now be a file called `atomic.config.json` in the folder where you ran this command. The contents will look like this:
+
+```json
+{
+  "outputFolder": "./src/ontologies",
+  "moduleAlias": "@tomic/lib",
+  "ontologies": []
+}
+```
+
+> If you want to change the location where the files are generated you can change the `outputFolder` field.
+
+Next add the subjects of your atomic ontologies to the `ontologies` array in the config.
+
+Now we will generate the ontology files. We do this by running the `ad-generate ontologies` command. If your ontologies don't have public read rights you will have to add an agent secret to the command that has access to these resources.
+
+```
+ad-generate ontologies --agent <AGENT_SECRET>
+```
+
+> Agent secret can also be preconfigured in the config **but be careful** when using version control as you can easily leak your secret this way.
+
+After running the command the files will have been generated in the specified output folder along with an `index.ts` file. The only thing left to do is to register our ontologies with @tomic/lib. This should be done as soon in your apps runtime lifecycle as possible, for example in your App.tsx when using React or root index.ts in most cases.
+
+```typescript
+import { initOntologies } from './ontologies';
+
+initOntologies();
+```
+
+### Using the types
+
+If everything went well the generated files should now be in the output folder.
+In order to gain the benefit of the typings we will need to annotate our resource with its respective class like follows:
+
+```typescript
+import { Book, creativeWorks } from './ontologies/creativeWorks.js';
+
+const book = await store.getResourceAsync<Book>(
+  'https://mybookstore.com/books/1',
+);
+```
+
+Now we know what properties are required and recommend on this resource so we can safely infer the types
+
+Because we know `written-by` is a required property on book we can safely infer type string;
+
+```typescript
+const authorSubject = book.get(creativeWorks.properties.writtenBy); // string
+```
+
+`description` has datatype Markdown and is inferred as string but it is a recommended property and might therefore be undefined
+
+```typescript
+const description = book.get(core.properties.description); // string | undefined
+```
+
+If the property is not in any ontology we can not infer the type so it will be of type `JSONValue`
+(this type includes `undefined`)
+
+```typescript
+const unknownProp = book.get('https://unknownprop.site/prop/42'); // JSONValue
+```
+
+### Props shorthand
+
+Because you have initialised your ontologies before lib is aware of what properties exist and what their name and type is. Because of this it is possible to use the props field on a resource and get full intellisense and typing on it.
+
+```typescript
+const book = await store.getResourceAsync<Book>(
+  'https://mybookstore.com/books/1',
+);
+
+const name = book.props.name; // string
+const description = book.props.description; // string | undefined
+```
+
+> The props field is a computed property and is readonly.
+>
+> If you have to read very large number of properties at a time it is more efficient to use the `resource.get()` method instead of the props field because the props field iterates over the resources propval map.
+
+## Configuration
+
+@tomic/cli loads the config file from the root of your project. This file should be called `atomic.config.json` and needs to conform to the following interface.
+
+```typescript
+interface AtomicConfig {
+  /**
+   * Path relative to this file where the generated files should be written to.
+   */
+  outputFolder: string;
+
+  /**
+   * [OPTIONAL] The @tomic/lib module identifier.
+   * The default should be sufficient in most but if you have given the module an alias you should change this value
+   */
+  moduleAlias?: string;
+
+  /**
+   * [OPTIONAL] The secret of the agent that is used to access your atomic data server. This can also be provided as a command line argument if you don't want to store it in the config file.
+   * If left empty the public agent is used.
+   */
+  agentSecret?: string;
+
+  /** The list of subjects of your ontologies */
+  ontologies: string[];
+}
+```
+
+Running `ad-generate init` will create this file for you that you can then tweak to your own preferences.

browser/cli/src/commands/init.ts

@@ -0,0 +1,33 @@
+/* eslint-disable no-console */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const TEMPLATE_CONFIG_FILE = {
+  outputFolder: './src/ontologies',
+  moduleAlias: '@tomic/lib',
+  ontologies: [],
+};
+
+export const initCommand = async (args: string[]) => {
+  const forced = args.includes('--force') || args.includes('-f');
+  const filePath = path.join(process.cwd(), 'atomic.config.json');
+  const stat = fs.statSync(filePath);
+
+  if (stat.isFile() && !forced) {
+    return console.error(
+      chalk.red(
+        `ERROR: File already exists. If you meant to override the existing file, use the command with the ${chalk.cyan(
+          '--force',
+        )} flag.`,
+      ),
+    );
+  }
+
+  console.log(chalk.cyan('Creating atomic.config.json'));
+
+  const template = JSON.stringify(TEMPLATE_CONFIG_FILE, null, 2);
+  fs.writeFileSync(filePath, template);
+
+  console.log(chalk.green('Done!'));
+};

browser/cli/src/commands/ontologies.ts

@@ -0,0 +1,49 @@
+/* eslint-disable no-console */
+
+import * as fs from 'fs';
+import chalk from 'chalk';
+
+import * as path from 'path';
+import { generateOntology } from '../generateOntology.js';
+import { atomicConfig } from '../config.js';
+import { generateIndex } from '../generateIndex.js';
+
+export const ontologiesCommand = async (_args: string[]) => {
+  console.log(
+    chalk.blue(
+      `Found ${chalk.red(
+        Object.keys(atomicConfig.ontologies).length,
+      )} ontologies`,
+    ),
+  );
+
+  for (const subject of Object.values(atomicConfig.ontologies)) {
+    write(await generateOntology(subject));
+  }
+
+  console.log(chalk.blue('Generating index...'));
+
+  write(generateIndex(atomicConfig.ontologies));
+
+  console.log(chalk.green('Done!'));
+};
+
+const write = ({
+  filename,
+  content,
+}: {
+  filename: string;
+  content: string;
+}) => {
+  console.log(chalk.blue(`Writing ${chalk.red(filename)}...`));
+
+  const filePath = path.join(
+    process.cwd(),
+    atomicConfig.outputFolder,
+    filename,
+  );
+
+  fs.writeFileSync(filePath, content);
+
+  console.log(chalk.blue('Wrote to'), chalk.cyan(filePath));
+};

browser/cli/src/config.ts

@@ -0,0 +1,28 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface AtomicConfig {
+  /**
+   * Path relative to this file where the generated files should be written to.
+   */
+  outputFolder: string;
+  /**
+   * [OPTIONAL] The @tomic/lib module identifier.
+   * The default should be sufficient in most but if you have given the module an alias you should change this value
+   */
+  moduleAlias?: string;
+  /**
+   * [OPTIONAL] The secret of the agent that is used to access your atomic data server. This can also be provided as a command line argument if you don't want to store it in the config file.
+   * If left empty the public agent is used.
+   */
+  agentSecret?: string;
+  /** The list of subjects of your ontologies */
+
+  ontologies: string[];
+}
+
+export const atomicConfig: AtomicConfig = JSON.parse(
+  fs
+    .readFileSync(path.resolve(process.cwd(), './atomic.config.json'))
+    .toString(),
+);

browser/cli/src/generateBaseObject.ts

@@ -0,0 +1,72 @@
+import { Resource, urls } from '@tomic/lib';
+import { store } from './store.js';
+import { camelCaseify } from './utils.js';
+
+export type ReverseMapping = Record<string, string>;
+
+type BaseObject = {
+  classes: Record<string, string>;
+  properties: Record<string, string>;
+};
+
+export const generateBaseObject = async (
+  ontology: Resource,
+): Promise<[string, ReverseMapping]> => {
+  if (ontology.error) {
+    throw ontology.error;
+  }
+
+  const classes = ontology.get(urls.properties.classes) as string[];
+  const properties = ontology.get(urls.properties.properties) as string[];
+  const name = camelCaseify(ontology.title);
+
+  const baseObj = {
+    classes: await listToObj(classes),
+    properties: await listToObj(properties),
+  };
+
+  const objStr = `export const ${name} = {
+    classes: ${recordToString(baseObj.classes)},
+    properties: ${recordToString(baseObj.properties)},
+  } as const`;
+
+  return [objStr, createReverseMapping(name, baseObj)];
+};
+
+const listToObj = async (list: string[]): Promise<Record<string, string>> => {
+  const entries = await Promise.all(
+    list.map(async subject => {
+      const resource = await store.getResourceAsync(subject);
+
+      return [camelCaseify(resource.title), subject];
+    }),
+  );
+
+  return Object.fromEntries(entries);
+};
+
+const recordToString = (obj: Record<string, string>): string => {
+  const innerSting = Object.entries(obj).reduce(
+    (acc, [key, value]) => `${acc}\n\t${key}: '${value}',`,
+    '',
+  );
+
+  return `{${innerSting}\n   }`;
+};
+
+const createReverseMapping = (
+  ontologyTitle: string,
+  obj: BaseObject,
+): ReverseMapping => {
+  const reverseMapping: ReverseMapping = {};
+
+  for (const [name, subject] of Object.entries(obj.classes)) {
+    reverseMapping[subject] = `${ontologyTitle}.classes.${name}`;
+  }
+
+  for (const [name, subject] of Object.entries(obj.properties)) {
+    reverseMapping[subject] = `${ontologyTitle}.properties.${name}`;
+  }
+
+  return reverseMapping;
+};