cdcarson / frieda Goto Github PK

The API has changed a bit since the tests were written (e.g. added ViewDatabase.) Rewrite tests.

The types in frieda-models.ts show up in vscode autocomplete. This should not happen. I think it's because the file does not have a default export.

I think adding

export default {};

to the bottom will fix.

The changes made to the API class names (#6) are not reflected in the generated code. Offending names:

ModelDb, ViewDb

Mainly write tests for the parse functions in app/parse-schema.ts.

In a js project the ModelWhereInput type is taking the union (??) of Sql and Partial<M> rather than inferring that it's a Partial<M>. See below.

I never noticed this before in typescript project. I'm pretty sure this is a javascript thing, but need to check. In any case the following needs to be looked at. It could probably be improved.

Add a "Field Casting" section under "Field Types".

• Diff between types and casting (this should also be mentioned at the top of "Field Types".)
• The casting algorithms.

Here's kinda what we want to say, in the broader context of types:

The javascript type of a field determines the casting algorithm. It's up to you to choose an appropriate javascript type for each field. Typing a bigint column as a number field makes sense in some circumstances; typing a varchar column as boolean will (at least) produce unexpected results.

While writing the docs I realized that the filenames are not really friendly.

• It's not obvious that schema-definition.d.ts is where you edit the schema, plus it kinda conflicts with generated/schema-definition.js
• The *-db names are not adequately grouped
• There are too many files on this level. The only file that really needs to be at the top of generated if models.d.ts. (Since it's the only one that deals with type imports.
• Everything should be exported from index.js. There's a potential gotcha -- do we then need to have more d.ts files? Need to check that.
• While we're at it, change the class names to be ApplicationDatabase, ModelsDatabase and TransactionDatabase, with matching filenames.

So, new structure:

• [outputPath]
  • model-types.d.ts
  • generated
    • index.js
    • models.d.ts
    • database-classes
      • application-database.js
      • models-database.js
      • transaction-database.js
    • schema
      • schema-definition.js
      • schema-cast-map.js
    • search
      • search-indexes.js

In some cases tooling will overcome this automatically, i.e. allow typescript source code to be consumed in a javascript project. For example, Frieda works fine in a SvelteKit/Vite project using javascript. (I have no idea whether this is the default Vite behavior, or some SvelteKit or Vite setting.)

In other cases there needs to be a build step defined by the user to compile the generated code. It'd be nice to figure this out, and let the user choose to generate javascript automatically.

Documentation for

• Generated classes
• API classes
• API types
• Utilities

Too many generated files, which means having to explain/expose too much.

There should be two generated (code) files:

• frieda.ts (all the generated non-editable code)
• frieda-models.ts (the editable types)

There's no reason to expose these types -- they just make the code readable.

The quick start example has the wrong class names:

ℹ Quick start example:
--------------------------------------------------------
// src/lib/db/get-db.js
// Example quick start code. The `getDb`
// function returns a singleton `AppDb` instance.

import { connect } from '@planetscale/database';
// get the database URL...
import { DATABASE_URL } from '$env/static/private';
// import the generated AppDb class...
import { AppDb } from './generated/app-db';

/** @type {AppDb|undefined} */
let _appDb = undefined;

/** @returns {AppDb} */
export const getDb = () => {
  if (!_appDb) {
    _appDb = new AppDb(connect({ url: DATABASE_URL }));
  }
  return _appDb;
};
--------------------------------------------------------
Done in 1358ms. 🦮

Right now in the API we have ViewDb with find* methods which we use for database views, extended by ModelDb which has full on CrUD methods. This is confusing in the docs, since both views and tables are "models".

Also (see #2) we're renaming the generated database classes to *Database (from *Db). So, new names for the API databases:

• BaseDb -> BaseDatabase
• ViewDb -> ViewDatabase
• ModelDb -> TableDatabase

Because the types are not exported, eslint warns, e.g...

'Article' is defined but never used.

Fix: add...

/* eslint-disable @typescript-eslint/no-unused-vars */

to the top of the file.

Just link to the docs

Just dump the raw sql.

Right now, there's an option to continue anyway.

It should:

• link to the docs about this in the preceding warning
• bail