@shaferllc/keel 0.59.0 → 0.68.0

package/docs/examples/models.ts

@@ -0,0 +1,239 @@
+// Type-check harness for docs/models.md. Every type-checkable snippet in the
+// guide and its API reference is exercised here against the real exports, so a
+// renamed method or wrong argument type fails `npm run typecheck:docs`.
+// Compile-only — never executed.
+import {
+  Model,
+  Relation,
+  HasOne,
+  HasMany,
+  BelongsTo,
+  BelongsToMany,
+  setConnection,
+  json,
+  type Connection,
+  type Row,
+  type CastType,
+  type Casts,
+} from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const roleId: number;
+
+/* ------------------------------- define models ------------------------------ */
+
+export class User extends Model {
+  static table = "users";
+  static primaryKey = "id"; // default
+
+  declare id: number;
+  declare email: string;
+  declare name: string;
+
+  posts() {
+    return this.hasMany(Post);
+  }
+  profile() {
+    return this.hasOne(Profile);
+  }
+  roles() {
+    return this.belongsToMany(Role);
+  }
+}
+
+export class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  static casts = {
+    published: "boolean", // 1/0        <-> true/false
+    views: "int", // "10"       ->  10
+    meta: "json", // '{"a":1}'  <-> { a: 1 }   (also "array")
+    posted_at: "date", // ISO string <-> Date
+  } as const;
+
+  declare id: number;
+  declare title: string;
+  declare published: boolean;
+  declare meta: Record<string, unknown>;
+
+  author() {
+    return this.belongsTo(User);
+  }
+}
+
+export class Profile extends Model {
+  static table = "profiles";
+  declare id: number;
+}
+
+export class Role extends Model {
+  static table = "roles";
+  declare id: number;
+}
+
+/* -------------------------------- connection -------------------------------- */
+
+export function connect() {
+  // The mock uses `as Connection` because `select` is declared generic — a
+  // concrete implementation returns `Row[]`, which the compiler can't match to
+  // an arbitrary `T` without the cast.
+  const connection = {
+    select: async () => [] as Row[],
+    write: async () => ({ rowsAffected: 1, insertId: 1 }),
+  } as Connection;
+  setConnection(connection, "sqlite");
+}
+
+/* --------------------------------- reading ---------------------------------- */
+
+export async function reading() {
+  const all = await User.all();
+  const one = await User.find(1);
+  const orFail = await User.findOrFail(1);
+  const firstOne = await User.first();
+  const active = await User.where("active", true);
+  const rich = await User.query().where("age", ">", 18).orderBy("name").limit(10).get();
+  return { all, one, orFail, firstOne, active, rich };
+}
+
+/* --------------------------------- writing ---------------------------------- */
+
+export async function writing() {
+  const user = await User.create({ email: "a@b.com", name: "Ada" });
+
+  user.name = "Grace";
+  await user.save();
+
+  const draft = new User({ email: "new@x.com" });
+  await draft.save();
+  draft.id;
+
+  await user.delete();
+}
+
+/* -------------------------------- attribute casts --------------------------- */
+
+export async function casts() {
+  const post = await Post.find(1);
+  post?.published; // real boolean
+  post?.meta; // real object
+  if (post) {
+    post.published = false;
+    await post.save();
+  }
+}
+
+/* ------------------------------- mass assignment ---------------------------- */
+
+export async function massAssignment(request: { all(): Row }) {
+  class Article extends Model {
+    static table = "articles";
+    static guarded = ["is_admin"];
+    declare title: string;
+  }
+
+  await Post.create({ title: "Hi", is_admin: true }); // is_admin dropped
+  const post = new Post();
+  post.fill(request.all()); // safe from over-posting
+  post.forceFill({ is_admin: true }); // explicit bypass
+
+  const article = new Article();
+  article.fill(request.all());
+}
+
+/* --------------------------------- serializing ------------------------------ */
+
+export async function serializing(user: User) {
+  user.toJSON();
+  json(user);
+  user.fill({ name: "X" });
+}
+
+/* -------------------------------- relationships ----------------------------- */
+
+export async function relationships(user: User, post: Post) {
+  const posts = await user.posts(); // Post[]
+  const author = await post.author(); // User | null
+
+  const recent = await user.posts().query().orderBy("created_at", "desc").limit(5).get();
+  return { posts, author, recent };
+}
+
+/* -------------------------------- eager loading ----------------------------- */
+
+export async function eagerLoading() {
+  const users = await User.all();
+  await User.load(users, "posts", "roles");
+
+  const loaded = users[0]?.getRelation<Post[]>("posts");
+  users[0]?.toJSON();
+  return { loaded };
+}
+
+/* --------------------------------- many-to-many ----------------------------- */
+
+export async function manyToMany(user: User) {
+  await user.roles().attach(roleId);
+  await user.roles().attach(roleId, { assigned_at: "now" });
+  await user.roles().detach(roleId);
+  await user.roles().detach();
+  await user.roles().sync([1, 2, 3]);
+}
+
+/* -------------------------------- override keys ----------------------------- */
+
+export function overrideKeys(user: User, post: Post) {
+  const a: HasMany<Post> = user.hasMany(Post, "authored_by", "id");
+  const b: BelongsTo<User> = post.belongsTo(User, "owner_id", "id");
+  const c: BelongsToMany<Role> = user.belongsToMany(Role, "user_roles", "user_id", "role_id");
+  const d: HasOne<Profile> = user.hasOne(Profile, "user_id", "id");
+  return { a, b, c, d };
+}
+
+/* --------------------------- relation base / subclasses --------------------- */
+
+export async function relationSurface(user: User) {
+  const rel: HasMany<Post> = user.posts();
+  const base: Relation<Post, Post[]> = rel;
+  base.query();
+  const viaGet = await base.get();
+  const viaAwait = await base; // PromiseLike — then() resolves to the result
+  rel.query();
+
+  const one: HasOne<Profile> = user.hasOne(Profile);
+  const oneResult = await one.get(); // Profile | null
+  return { viaGet, viaAwait, oneResult };
+}
+
+/* --------------------------- static configuration --------------------------- */
+
+export function configuration() {
+  User.table;
+  User.primaryKey;
+  Post.fillable;
+  Post.guarded;
+  Post.casts;
+  Post.timestamps;
+  Post.createdAtColumn;
+  Post.updatedAtColumn;
+  Post.query();
+}
+
+export async function ormMaturity() {
+  const page = await User.paginate(2, 15); // Paginated<User>
+  const users: User[] = page.data;
+  const meta = { total: page.total, currentPage: page.currentPage, lastPage: page.lastPage };
+
+  const tag = await User.firstOrCreate({ email: "a@b.com" }, { name: "Ada" });
+  const sub = await User.updateOrCreate({ email: "a@b.com" }, { name: "Grace" });
+
+  await tag.update({ name: "Ada L." });
+  await sub.refresh();
+  return { users, meta, tag, sub };
+}
+
+/* ---------------------------- interface / type seams ------------------------ */
+
+const castType: CastType = "boolean";
+const castMap: Casts = { published: "boolean", views: "int", meta: "json" };
+export { castType, castMap };

package/docs/examples/notification.ts

@@ -0,0 +1,124 @@
+// Type-check harness for docs/notifications.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed method or
+// wrong argument type fails `npm run typecheck:docs`. Compile-only — never run.
+import {
+  Notification,
+  Notifier,
+  MailChannel,
+  DatabaseChannel,
+  ArrayChannel,
+  routeFor,
+  notify,
+  setNotifier,
+  getNotifier,
+  type Notifiable,
+  type MailContent,
+  type Channel,
+} from "@shaferllc/keel/core";
+
+declare const user: Notifiable;
+declare const alice: Notifiable;
+declare const bob: Notifiable;
+
+export class InvoicePaid extends Notification {
+  constructor(private amount: number) {
+    super();
+  }
+  via(_notifiable: Notifiable) {
+    return ["mail", "database"];
+  }
+  toMail(): MailContent {
+    return { subject: "Payment received", text: `Thanks for $${this.amount}.` };
+  }
+  toArray() {
+    return { amount: this.amount };
+  }
+}
+
+export class QueuedInvoicePaid extends Notification {
+  shouldQueue = true;
+  via() {
+    return ["array"];
+  }
+  toArray() {
+    return {};
+  }
+}
+
+export async function sending() {
+  await notify(user, new InvoicePaid(4200));
+  await notify([alice, bob], new InvoicePaid(4200));
+}
+
+export function routing() {
+  const mail = routeFor(user, "mail");
+  const dbId = routeFor(user, "database");
+  return { mail, dbId };
+}
+
+export function registerChannels() {
+  setNotifier(new Notifier().channel("database", new DatabaseChannel()));
+  getNotifier().channel("slack", slack);
+}
+
+// A custom channel — the illustrative Slack snippet, compiling.
+export const slack: Channel = {
+  async send(notifiable, notification) {
+    const payload = notification.toArray?.(notifiable) ?? {};
+    void payload;
+    // POST payload to a Slack webhook via fetch…
+  },
+};
+
+export async function customChannel() {
+  setNotifier(new Notifier().channel("slack", slack));
+}
+
+export async function inTests() {
+  const array = new ArrayChannel();
+  setNotifier(new Notifier().channel("array", array));
+
+  await notify(user, new QueuedInvoicePaid());
+
+  const first = array.sent[0];
+  return { count: array.sent.length, notification: first?.notification };
+}
+
+// API-reference entries
+export async function reference() {
+  await notify(user, new InvoicePaid(4200));
+  setNotifier(new Notifier().channel("database", new DatabaseChannel()));
+  getNotifier().channel("slack", slack);
+
+  routeFor(user, "mail");
+  routeFor(user, "database");
+
+  const notifier = new Notifier()
+    .channel("database", new DatabaseChannel())
+    .channel("array", new ArrayChannel());
+  await notifier.send(user, new InvoicePaid(4200));
+  await new Notifier().send(user, new InvoicePaid(4200));
+
+  new DatabaseChannel();
+  new DatabaseChannel("alerts");
+
+  await new MailChannel().send(user, new InvoicePaid(4200));
+  await new DatabaseChannel().send(user, new InvoicePaid(4200));
+
+  const arrayChannel = new ArrayChannel();
+  await arrayChannel.send(user, new InvoicePaid(4200));
+  return arrayChannel.sent[0]?.notification;
+}
+
+// Interface / type seams
+const content: MailContent = {
+  subject: "Welcome",
+  html: "<h1>Hi</h1>",
+  to: "override@app.com",
+};
+
+const channel: Channel = {
+  async send(_notifiable, _notification) {},
+};
+
+export { content, channel };

package/docs/examples/providers.ts

@@ -0,0 +1,123 @@
+// Type-check harness for docs/providers.md. Every type-checkable snippet in the
+// guide is exercised here against the real exports, so a renamed method or wrong
+// signature fails `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  ServiceProvider,
+  Config,
+  Application,
+  type ProviderClass,
+} from "@shaferllc/keel/core";
+
+// Stand-in services the snippets bind — shape-only, never run.
+class StripeClient {
+  constructor(_key: string) {}
+}
+class SearchIndex {}
+class SearchClient {
+  static connect(_url: string): Promise<SearchClient> {
+    return Promise.resolve(new SearchClient());
+  }
+  warm(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+class Cache {
+  warm(_keys: string[]): Promise<void> {
+    return Promise.resolve();
+  }
+}
+class Redis {
+  quit(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+// --- The lifecycle (all four hooks) ----------------------------------------
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.bind("clock", () => new Date().toISOString());
+  }
+
+  boot(): void {
+    // Phase 2 — safe to resolve.
+  }
+
+  async ready(): Promise<void> {
+    await this.app.make(Cache).warm(["home", "pricing"]);
+  }
+
+  async shutdown(): Promise<void> {
+    await this.app.make(Redis).quit();
+  }
+}
+
+// --- The `app` reference ---------------------------------------------------
+export class SearchServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton("search", () => new SearchIndex());
+  }
+
+  boot(): void {
+    const debug = this.app.config().get("app.debug", false);
+    this.app.router().get("/health", () => "ok");
+    void debug;
+  }
+}
+
+// --- A realistic example ---------------------------------------------------
+export class BillingServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton(StripeClient, (app) => {
+      const key = app.make(Config).get<string>("services.stripe.key");
+      return new StripeClient(key);
+    });
+  }
+
+  boot(): void {
+    // e.g. register webhooks, warm a cache, etc.
+  }
+}
+
+// --- Async providers -------------------------------------------------------
+export class AsyncSearchProvider extends ServiceProvider {
+  async register(): Promise<void> {
+    const client = await SearchClient.connect("https://search.example");
+    this.app.instance(SearchClient, client);
+  }
+
+  async boot(): Promise<void> {
+    await this.app.make(SearchClient).warm();
+  }
+}
+
+// --- Registering a provider ------------------------------------------------
+export const providers: ProviderClass[] = [
+  AppServiceProvider,
+  BillingServiceProvider,
+];
+
+// --- Booting the providers -------------------------------------------------
+export async function bootApp(): Promise<Application> {
+  const app = new Application();
+  app.register(AppServiceProvider);
+  return app.boot(providers);
+}
+
+// --- Parameterized providers (plugin-style options) ------------------------
+export class RateLimitProvider extends ServiceProvider<{ max: number }> {
+  boot(): void {
+    const max: number = this.options.max; // typed via the generic
+    void max;
+  }
+}
+
+export async function registerWithOptions(): Promise<Application> {
+  const app = new Application();
+  app.register(RateLimitProvider, { max: 100 });
+  app.register(RateLimitProvider, { max: 20 }); // again, different options
+  return app.boot([], { discoverConfig: false, config: { app: {} } });
+}
+
+// --- ProviderClass as a value ----------------------------------------------
+const provider: ProviderClass = SearchServiceProvider;
+export { provider };