@alstar/studio 0.0.0-beta.1 → 0.0.0-beta.10

package/queries/getBlocks.ts

@@ -0,0 +1,214 @@
+import { DatabaseSync } from "node:sqlite";
+import { sql } from "../utils/sql.ts";
+
+// --- Field & block definitions ---
+type FieldType = 'text' | 'slug' | 'markdown' | 'blocks' | 'image';
+
+interface BaseField {
+  label: string;
+  type: FieldType;
+}
+
+interface TextField extends BaseField {
+  type: 'text' | 'slug' | 'markdown';
+}
+
+interface ImageField extends BaseField {
+  type: 'image';
+}
+
+interface BlocksField extends BaseField {
+  type: 'blocks';
+  children: Record<string, BlockDef>;
+}
+
+type FieldDef = TextField | ImageField | BlocksField;
+
+interface BlockDef {
+  label: string;
+  type: string;
+  fields: Record<string, FieldDef>;
+}
+
+// --- Identity helpers (preserve literal types) ---
+export function defineField<T extends FieldDef>(field: T) {
+  return field;
+}
+
+export function defineBlock<T extends BlockDef>(block: T) {
+  return block;
+}
+
+export function defineStructure<T extends Record<string, BlockDef>>(structure: T) {
+  return structure;
+}
+
+// --- Type mapping from structure to data ---
+type FieldToType<F extends FieldDef> =
+  F['type'] extends 'text' | 'slug' | 'markdown' ? string :
+  F['type'] extends 'image' ? string :
+  F['type'] extends 'blocks'
+    ? {
+        [K in keyof F['children']]: {
+          type: K;
+          data: BlockData<F['children'][K]>;
+        }
+      }[keyof F['children']][]
+    : never;
+
+type BlockData<B extends BlockDef> = {
+  [K in keyof B['fields']]: FieldToType<B['fields'][K]>;
+};
+
+type StructureData<S extends Record<string, BlockDef>> = {
+  [K in keyof S]: BlockData<S[K]>;
+};
+
+// This will be inferred after you define your structure
+export type CMSData<S extends Record<string, BlockDef>> = StructureData<S>;
+
+
+interface DBBase {
+  id: number;
+  created_at: string;
+  updated_at: string;
+  name: string;
+  label: string;
+  type: string;
+  sort_order: number;
+  value: string | null;
+  options: any;
+  status: string;
+  parent_id: number | null;
+}
+
+export function buildTypedForest<
+  S extends Record<string, BlockDef>,
+  K extends keyof S
+>(
+  rows: DBBase[],
+  rootDef: S[K]
+): CMSData<S>[K][] {
+  const map = new Map<number, DBBase & { children: DBBase[] }>();
+
+  // Initialize with children arrays
+  for (const r of rows) {
+    map.set(r.id, { ...r, children: [] });
+  }
+
+  // Link children to parents
+  const roots: (DBBase & { children: DBBase[] })[] = [];
+  for (const r of rows) {
+    const node = map.get(r.id)!;
+    if (r.parent_id === null) {
+      roots.push(node);
+    } else {
+      const parent = map.get(r.parent_id);
+      if (parent) parent.children.push(node);
+    }
+  }
+
+  // Recursive transformer: maps a DB row into typed data
+  function transformNode<D extends FieldDef | BlockDef>(
+    node: DBBase & DBBase['type'] extends 'blocks' ? { children: DBBase[] } : {},
+    def: D
+  ): any {
+    if ('fields' in def) {
+      // It's a BlockDef
+      const result: any = {};
+      for (const key in def.fields) {
+        const fieldDef = def.fields[key];
+        const childNode = node.children.find(c => c.name === key);
+        result[key] = childNode
+          ? transformNode(childNode, fieldDef)
+          : getDefaultValue(fieldDef);
+      }
+      return result;
+    } else {
+      // It's a FieldDef
+      if (def.type === 'text' || def.type === 'slug' || def.type === 'markdown') {
+        return node.value ?? '';
+      }
+      if (def.type === 'image') {
+        return node.value ?? '';
+      }
+      if (def.type === 'blocks') {
+        return node.children.map(child => {
+          const childDef = def.children[child.name as keyof typeof def.children];
+          return {
+            type: child.name as keyof typeof def.children,
+            data: transformNode(child, childDef)
+          };
+        });
+      }
+    }
+  }
+
+  // Provide safe defaults for missing fields
+  function getDefaultValue(fieldDef: FieldDef): any {
+    if (fieldDef.type === 'blocks') return [];
+    return '';
+  }
+
+  // Map all root nodes into typed data
+  return roots.map(root => transformNode(root, rootDef));
+}
+
+
+function rootQuery(filterSql: string, depthLimit?: number) {
+  const depthLimitClause =
+    depthLimit !== undefined ? `WHERE d.depth + 1 <= ${depthLimit}` : '';
+
+  return sql`
+    with recursive
+      ancestors as (
+        select
+          id, created_at, updated_at, name, label, type, sort_order, value, options, status, parent_id,
+          0 as depth
+        from blocks
+        where ${filterSql}
+        union all
+        select
+          b.id, b.created_at, b.updated_at, b.name, b.label, b.type, b.sort_order, b.value, b.options, b.status, b.parent_id,
+          a.depth + 1
+        from blocks b
+        inner join ancestors a on b.id = a.parent_id
+      ),
+      roots as (
+        select * from ancestors where parent_id is null
+      ),
+      descendants as (
+        select * from roots
+        union all
+        select
+          b.id, b.created_at, b.updated_at, b.name, b.label, b.type, b.sort_order, b.value, b.options, b.status, b.parent_id,
+          d.depth + 1
+        from blocks b
+        inner join descendants d on b.parent_id = d.id ${depthLimitClause}
+      )
+    select * from descendants
+    order by parent_id, sort_order
+  `;
+}
+
+export function queryTypedRoot<
+  S extends Record<string, BlockDef>,
+  K extends keyof S
+>(
+  db: DatabaseSync,
+  structure: S,
+  blockType: K,
+  opts: { id?: number; depthLimit?: number }
+): CMSData<S>[K][] {
+  let filterSql: string;
+  if (opts.id !== undefined) {
+    filterSql = `id = ${opts.id}`;
+  } else {
+    filterSql = `type = '${String(structure[blockType].type)}'`;
+  }
+
+  const sql = rootQuery(filterSql, opts.depthLimit);
+  const rows = db.prepare(sql).all() as unknown as DBBase[];
+
+  return buildTypedForest(rows, structure[blockType]);
+}

package/queries/index.ts

@@ -1,98 +1,2 @@
-import { db } from '@alstar/db'
-import { sql } from '../utils/sql.ts'
-import { type DBBlock } from '../types.ts'
-import { buildBlockTree } from '../utils/buildBlocksTree.ts'
-
-export const blocks = (options: {
-  parent: string | number | null
-}): DBBlock[] | null => {
-  const q =
-    options.parent === null
-      ? sql`
-          select
-            *
-          from
-            blocks
-          where
-            parent_block_id is null;
-        `
-      : sql`
-          select
-            *
-          from
-            blocks
-          where
-            parent_block_id = ?;
-        `
-
-  const transaction = db.database.prepare(q)
-
-  if (options.parent === null) {
-    return transaction.all() as unknown as DBBlock[]
-  } else {
-    return transaction.all(options.parent) as unknown as DBBlock[]
-  }
-}
-
-export const block = (
-  query: Record<string, string | null>,
-  options?: { recursive: boolean },
-): DBBlock | null => {
-  const str = Object.keys(query)
-    .map((key) => `${key.replace('parent', 'parent_block_id')} = ?`)
-    .join(' AND ')
-
-  const q = options?.recursive
-    ? sql`
-        with recursive
-          block_hierarchy as (
-            -- Anchor member: the root block, depth = 0
-            select
-              b.*,
-              0 as depth
-            from
-              blocks b
-            where
-              b.id = ? -- Replace 5 with your root block ID
-            union all
-            -- Recursive member: find children and increment depth
-            select
-              b.*,
-              bh.depth + 1 as depth
-            from
-              blocks b
-              inner join block_hierarchy bh on b.parent_block_id = bh.id
-          )
-        select
-          *
-        from
-          block_hierarchy
-        order by
-          sort_order;
-      `
-    : sql`
-        select
-          *
-        from
-          blocks
-        where
-          ${str};
-      `
-
-  const transaction = db.database.prepare(q)
-
-  try {
-    if (options?.recursive) {
-      const res = transaction.all(query.id) as unknown as any[]
-      return (buildBlockTree(res) as any) || null
-    }
-    return (
-      (transaction.get(...Object.values(query)) as unknown as DBBlock) || null
-    )
-  } catch (error) {
-    console.log('error')
-    return null
-  }
-}
-
-export const query = { blocks, block }
+export * as query from './block.ts'
+export { getBlockTrees } from './getBlockTrees.ts'

package/queries/structure-types.ts

@@ -0,0 +1,97 @@
+// structure-types.ts
+import { type DBBase } from "./db-types.ts";
+
+/**
+ * Extract helpers
+ */
+type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+
+/**
+ * Field definition shape inferred from defineField(...) (the runtime helper)
+ * We keep it generic as "any" shape but with the important properties present
+ */
+type FieldDef = {
+  readonly name: string;
+  readonly type: string;
+  readonly fields?: readonly any[]; // only present when type === 'blocks'
+};
+
+/**
+ * Block definition shape inferred from defineBlock(...) (the runtime helper)
+ */
+type BlockDef = {
+  readonly name: string;
+  readonly type: string;
+  readonly fields?: readonly FieldDef[];
+};
+
+/**
+ * Primitive field node (non-'blocks'): DBBase + kept fields but no children
+ */
+type PrimitiveFieldNode<TField extends FieldDef> =
+  DBBase & {
+    readonly name: TField["name"];
+    readonly type: TField["type"];
+    // no children (leaf), no nested fields
+    readonly children?: [];
+    readonly fields?: {}; // empty object for leaf
+  };
+
+/**
+ * For 'blocks' typed field, we need:
+ * - the block node representing the 'blocks' wrapper (has DBBase props)
+ * - its 'children' are an array of BlockNodes corresponding to nested block defs supplied in the field's 'fields' array
+ * - its 'fields' property is the mapping of its own child-field names (can be empty)
+ */
+type BlocksFieldNode<
+  TField extends FieldDef,
+  TFieldDefs extends readonly BlockDef[]
+> = DBBase & {
+  readonly name: TField["name"];      // e.g. "blocks" or "images"
+  readonly type: "blocks";            // literally 'blocks'
+  readonly children: BlockNodeFromBlockDefs<TFieldDefs>[]; // children are instances of the nested blocks
+  readonly fields: FieldsFromFieldDefs<TFieldDefs[number]["fields"]>; // the blocks-wrapper's own fields mapping (if any)
+};
+
+/**
+ * Build the 'fields' object for a set of FieldDef[].
+ * Maps each field name -> either PrimitiveFieldNode or BlocksFieldNode recursively.
+ */
+type FieldsFromFieldDefs<TDefs> =
+  // If no fields
+  TDefs extends readonly any[]
+    ? {
+        // For each field F in TDefs, map F['name'] -> node type
+        [F in ArrayElement<TDefs> as F extends { name: infer N extends string } ? N : never]:
+          F extends { type: "blocks"; fields: readonly BlockDef[] }
+            ? BlocksFieldNode<F, F["fields"]>
+            : PrimitiveFieldNode<F>;
+      }
+    : {};
+
+/**
+ * A Block node type for a particular BlockDef.
+ * - fields: mapping derived from the block's declared fields
+ * - children: by default [], because in our final shape all immediate children are placed under 'fields' of the parent.
+ *   BUT for nodes that are themselves 'blocks' wrappers (i.e. appear as a Block instance of a nested block def),
+ *   their 'children' will contain actual child blocks (these are handled via BlocksFieldNode above).
+ */
+export type BlockNode<T extends BlockDef> = DBBase & {
+  readonly name: T["name"];
+  readonly type: T["type"];
+  readonly fields: FieldsFromFieldDefs<T["fields"]>;
+  // for regular block nodes, children will usually be [] (top-level parent's children moved into fields)
+  readonly children: [];
+};
+
+/**
+ * Construct BlockNode unions for a set of block defs (used when blocks field has multiple block subdefs)
+ */
+type BlockNodeFromBlockDefs<TDefs extends readonly BlockDef[]> =
+  ArrayElement<TDefs> extends infer B ? (B extends BlockDef ? BlockNode<B> : never) : never;
+
+/**
+ * The top-level forest return type when you pass a structure: it's an array of BlockNode of any top-level BlockDef
+ */
+export type BlockTreeFromStructure<TStructure extends readonly BlockDef[]> =
+  BlockNodeFromBlockDefs<TStructure>;

package/readme.md

@@ -0,0 +1,205 @@
+# Alstar Studio
+
+Alstar Studio is a **fullstack framework** for building CMS-driven applications with **native Node.js** and **Hono**.
+
+
+## Installation
+
+Create a new project:
+
+```sh
+pnpm create @alstar
+```
+
+Follow the CLI prompts to set up a starter project in your chosen folder.
+
+
+## Development
+
+Start the dev server:
+
+```sh
+pnpm run dev
+```
+
+This runs a **Hono server**.
+
+The core app is created via `createStudio(structure)`, which returns the Hono app. This makes it possible to extend the server with plugins or custom settings:
+
+```ts
+const app = await createStudio(structure)
+// app.use(...) custom middleware
+```
+
+
+## Routing
+
+Pages are defined in the `/pages` directory.
+
+* Each `.ts` file becomes a route.
+* Dynamic routes are created with square brackets, e.g. `/pages/[slug].ts`.
+
+
+## CMS
+
+Access the CMS at:
+
+```
+/admin
+```
+
+### Defining Content Structure
+
+Pass a `Structure` object to `createStudio(structure)` to define the schema.
+
+Use the helpers:
+
+```ts
+import { 
+  defineBlock, 
+  defineField, 
+  defineStructure, 
+  defineBlockField 
+} from '@alstar/studio'
+```
+
+### Example: Schema Definition
+
+```ts
+const titleField = defineField({
+  label: 'Title',
+  type: 'text' | 'image' | 'markdown' | 'slug',
+  description: 'Page title'
+})
+
+const pageBuilder = defineBlockField({
+  label: 'Sections',
+  type: 'blocks',
+  children: {
+    hero: defineBlock({
+      label: 'Hero',
+      type: 'hero',
+      fields: { /* fields */ },
+    }),
+    gallery: defineBlock({
+      label: 'Gallery',
+      type: 'gallery',
+      fields: { /* fields */ },
+    }),
+  },
+})
+
+const entryBlock = defineBlock({
+  label: 'Entry',
+  type: 'entry',
+  fields: {
+    title: titleField,
+    builder: pageBuilder
+  }
+})
+
+export default defineStructure({
+  entry: entryBlock
+})
+```
+
+### Concepts
+
+* **Blocks** contain **fields**.
+* **Block fields** (`type: 'blocks'`) can nest multiple block types under `children`.
+* This enables **page builders** and reusable structures.
+
+All content is stored in a **SQLite database** (`studio.db`) and can be queried in the templates with the `query` module.
+
+
+## Frontend
+
+The framework encourages **server-side rendering** with Hono’s HTML helper (re-exported by the `@alstar/studio` package):
+
+```ts
+import { defineEntry, html } from '@alstar/studio'
+
+export default defineEntry((c) => {
+  const slug = c.req.param('slug')
+  
+  return html`
+    <h1>Hello World</h1>
+    <p>This page is: ${slug}</p>
+  `
+})
+```
+
+### Interactivity
+
+Even though the framework allows for having any library and tool for creating client-side behavior, it's recommended to use lightweight libraries such as:
+
+* [Datastar](https://data-star.dev/) (used internally by the Studio)
+* [Alpine.js](https://alpinejs.dev/)
+
+## Quickstart Example Project
+
+This example shows how to define a simple **page schema** and render it on the frontend.
+
+### 1. Define the CMS Schema (`./index.ts`)
+
+```ts
+import { createStudio, defineBlock, defineField, defineStructure } from '@alstar/studio'
+
+const page = defineBlock({
+  label: 'Page',
+  type: 'page',
+  fields: {
+    title: defineField({
+      label: 'Title',
+      type: 'text',
+    }),
+    slug: defineField({
+      label: 'Slug',
+      type: 'slug',
+    }),
+    body: defineField({
+      label: 'Body',
+      type: 'markdown',
+    }),
+  },
+})
+
+const structure = defineStructure({
+  page,
+})
+
+await createStudio(structure)
+```
+
+### 2. Create a Frontend Route (`/pages/[slug].ts`)
+
+```ts
+import { defineEntry, html, query } from '@alstar/studio'
+
+export default defineEntry(c) => {
+  const slug = c.req.param('slug')
+  const page = query.root({ type: 'slug', value: slug })
+
+  if (!page) return c.notFound()
+
+  return html`
+    <main>
+      <h1>${page.fields.title.value}</h1>
+      <article>${page.fields.body.value}</article>
+    </main>
+  `
+}
+```
+
+### 3. Run the Project
+
+```sh
+pnpm run dev
+```
+
+Visit:
+
+* **CMS admin**: `http://localhost:3000/admin`
+* **Frontend page**: `http://localhost:3000/my-first-page`
+
+Create a new page in the CMS, set its slug field to `my-first-page`, and the frontend will render it automatically.

package/schemas.ts

@@ -1,56 +1,5 @@
 import { sql } from './utils/sql.ts'
 
-// export const entriesTable = {
-//   tableName: 'entries',
-//   columns: sql`
-//     title TEXT not null, -- Title of the page
-//     slug TEXT not null unique, -- URL slug for the page
-//     meta_description TEXT -- Optional meta description for SEO
-//   `,
-// }
-
-// export const fieldTable = {
-//   tableName: 'fields',
-//   columns: sql`
-//     name TEXT not null, -- Name of the field (e.g., "content", "header", "image")
-//     type TEXT not null, -- Field type (e.g., "text", "image", "video")
-//     label TEXT not null, -- Field label (e.g., "Text", "Image", "Video")
-//     options TEXT -- Additional options or settings (can be a JSON string if needed)
-//   `,
-// }
-
-// export const entriesFieldsTable = {
-//   tableName: 'entry_fields',
-//   columns: sql`
-//     entry_id INTEGER not null, -- Foreign key to pages
-//     field_id INTEGER not null, -- Foreign key to fields
-//     position INTEGER, -- Optional: order of the field on the page
-//     content TEXT, -- Content of the field (e.g., text, image URL, etc.)
-//     foreign key (entry_id) references entries (id),
-//     foreign key (field_id) references fields (id)
-//   `,
-// }
-
-// export const entryTypeTable = {
-//   tableName: 'entry_types',
-//   columns: sql`
-//     name TEXT not null, -- Name of the field (e.g., "content", "header", "image")
-//     type TEXT not null, -- Field type (e.g., "text", "image", "video")
-//     label TEXT not null, -- Field label (e.g., "Text", "Image", "Video")
-//     options TEXT -- Additional options or settings (can be a JSON string if needed)
-//   `,
-// }
-
-// export const entryEntryTypeTable = {
-//   tableName: 'entry_entry_types',
-//   columns: sql`
-//     entry_id INTEGER not null, -- Foreign key to pages
-//     entry_type_id INTEGER not null, -- Foreign key to fields
-//     foreign key (entry_id) references entries (id),
-//     foreign key (entry_type_id) references entry_types (id)
-//   `,
-// }
-
 // -- Blocks
 export const blocksTable = {
   tableName: 'blocks',
@@ -58,10 +7,22 @@ export const blocksTable = {
     name TEXT not null,
     label TEXT not null,
     type TEXT not null,
-    sort_order INTEGER not null default 0,
     value TEXT,
     options JSON,
-    parent_block_id INTEGER,
-    foreign key (parent_block_id) references blocks (id)
+    status TEXT default 'enabled',
+    sort_order INTEGER not null default 0,
+    _depth INTEGER,
+    parent_id INTEGER,
+    foreign key (parent_id) references blocks (id)
+  `,
+}
+
+// -- API keys
+export const apiKeysTable = {
+  tableName: 'api_keys',
+  columns: sql`
+    name TEXT not null,
+    value TEXT,
+    hint TEXT
   `,
 }