miki-template 1.3.6 → 2.0.0

package/.eslintrc.json

@@ -0,0 +1,16 @@
+{
+  "env": {
+    "node": true,
+    "es2024": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+    "no-console": "off",
+    "semi": ["error", "always"]
+  }
+}

package/.github/release-notes/v1.3.7.md

@@ -0,0 +1,20 @@
+## v1.3.7 — Template discovery improvements
+
+- Add recursive/app-style template discovery so projects can place
+  templates in nested `templates/` folders (Django-style) and have
+  them discovered automatically.
+- `setupExpress` now expands `app.get('views')` to include nested
+  directories that contain template files so `res.render('name')`
+  works for templates located in project-level or package-level
+  `templates/` directories.
+- Expose `findTemplateInViews(name, roots)` helper and
+  `setAppTemplateDirNames()/getAppTemplateDirNames()` to configure
+  app-style template folder names.
+- Improve `res.render` fallback to use the recursive finder before
+  throwing Express's "Failed to lookup view" error.
+- Update docs and API reference with usage examples and migration
+  notes.
+
+CI: runs lint + tests (all passing locally). If you'd like a more
+comprehensive changelog, I can expand this with links to issues and
+code snippets.

package/API_REFERENCE.md

@@ -107,6 +107,33 @@ app.get('/', (req, res) => {
 });
 ```
 
+### Template discovery helpers
+
+`miki-template` exposes helpers to discover templates across multiple
+`views` roots and to configure what directory names are considered
+app-style template folders (e.g. `templates` or `app_templates`). These
+are useful for projects that place templates in nested app folders or
+package-level `templates/` directories.
+
+#### `findTemplateInViews(name, viewsDirs)`
+
+Search for a template by `name` across the provided `viewsDirs` array
+or single string. Performs direct resolution first, then a recursive
+search for bare filenames. Returns the absolute file path or `null`.
+
+Example:
+```js
+const found = require('miki-template').findTemplateInViews('detail', ['./views', './templates']);
+```
+
+#### `setAppTemplateDirNames(names)` / `getAppTemplateDirNames()`
+
+Configure and retrieve the directory names treated as app-style
+template folders when scanning the project tree. The default is
+`['templates']`. Use `setAppTemplateDirNames(['templates','app_templates'])`
+to include additional conventions.
+
+
 ---
 
 ### `registerTag(name, parserFn)`

package/README.md

@@ -132,6 +132,16 @@ app.listen(3000);
 
 > `setupExpress` calls `app.engine()`, `app.set('views')`, and `app.set('view engine')` for you, and patches `res.render` so `view#partial` is dispatched to the partial renderer (not the file system). It works equally well for `.miki` files — just pass `extension: 'miki'`.
 
+Note on template discovery: `setupExpress` now expands the `app.get('views')`
+value to include nested directories that contain template files. This
+means templates placed in project-level `templates/`, package-level
+`packages/*/templates/...`, or app-specific folders (e.g. `app_templates/`)
+will be discovered automatically when calling `res.render('name')`.
+
+If your project uses a different convention than `templates`, call
+`setAppTemplateDirNames()` to customize the names that the engine
+recognizes when scanning for app-style template folders.
+
 **The classic, fully manual setup still works** if you prefer it:
 
 ```javascript

package/benchmarks/report.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "small",
-    "syncAvgMs": "0.04",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.03"
   },
   {
     "name": "medium",
-    "syncAvgMs": "0.00",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.01"
   },
   {
     "name": "large",
-    "syncAvgMs": "0.00",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.01"
   }
 ]

package/docs/api.md

@@ -12,6 +12,9 @@ This document lists the public API exported by **miki-template** for developers
 | `express(options?)` | `express(object?) → function` | Factory that returns a view-engine function suitable for `app.engine(...)`. Honors `view#partial` selectors. | `app.engine('html', miki.express());` |
 | `setupExpress(app, opts?)` | `setupExpress(expressApp, object?) → void` | **One-line Express integration.** Wires `app.engine(...)`, `app.set('views')`, and patches `res.render` so `res.render('view#partial', ...)` returns just that partial. Options: `{ extension?, views?, async? }`. | `miki.setupExpress(app, { extension: 'html', views: './views' });` |
 | `expressPartialRenderer()` | `expressPartialRenderer() → function` | Express middleware that adds `res.renderPartial(view, locals)`. Useful as a drop-in HTMX helper without the full `setupExpress` shim. | `app.use(miki.expressPartialRenderer());` |
+| `findTemplateInViews(name, viewsDirs)` | `findTemplateInViews(string, string[]|string) → string|null` | Search for a template by name across one or more `views` roots. Performs direct resolution first (supports explicit paths and extensions), then a recursive search for bare filenames in subdirectories. Returns the absolute file path or `null` if not found. | `miki.findTemplateInViews('detail', ['./views', './templates'])` |
+| `setAppTemplateDirNames(names)` | `setAppTemplateDirNames(string[]|string) → void` | Configure which directory names are treated as app-style template folders when scanning (default: `['templates']`). Useful when projects use a different convention. | `miki.setAppTemplateDirNames(['templates','app_templates'])` |
+| `getAppTemplateDirNames()` | `getAppTemplateDirNames() → string[]` | Retrieve the current configured app-template directory names. | `const names = miki.getAppTemplateDirNames()` |
 | `renderPartialFromFile(filePath, partialName, context?, options?)` | `renderPartialFromFile(string, string, object?, object?) → string` | Load a file from disk and render only the named `{% partialdef %}`. | `miki.renderPartialFromFile('views/home.html', 'card', { user });` |
 | `renderPartialFromSource(source, partialName, context?, options?)` | `renderPartialFromSource(string, string, object?, object?) → string` | Render a single named partial directly from a template string. Walks the AST (and `extends` chain) to discover partials nested inside blocks. | `miki.renderPartialFromSource(src, 'card', ctx, { views });` |
 | `stripExpressContext(options)` | `stripExpressContext(object) → object` | Remove Express framework keys (`_locals`, `settings`, `cache`) from an options object. | `const ctx = stripExpressContext(res.locals);` |

package/docs/overview.md

@@ -44,6 +44,28 @@ Each module is deliberately **single‑responsibility** and fully typed via JSDo
 - **Partial definitions** – see `docs/partialdef.md`.
 - **Security considerations** – see `docs/security.md`.
 
+## Recursive and app-style template discovery
+
+`miki-template` now supports Django-style recursive template discovery. When you configure your views directory (via `miki.setupExpress(app, { views: './views' })` or by passing `views` to `render()`), the engine will:
+
+- Resolve direct paths like `nested/index` relative to each `views` directory.
+- If a bare template name (e.g. `card`) is used, recursively scan subfolders of the configured `views` directories to find `card.html` or `card.miki`.
+- Discover app-style `templates` directories located under application packages (e.g. `project/apps/product/templates/...`) and include them in the search.
+
+Configuration:
+
+- Programmatically set which folder names should be treated as app template roots via the API:
+
+	- `setAppTemplateDirNames(['templates', 'site_templates'])` — sets the list of folder names that will be discovered under the views root.
+	- `getAppTemplateDirNames()` — returns the current list.
+
+Examples:
+
+	- `render('home#card', ctx, { views: './views' })` will search `./views` and any `templates/` subfolders for `home.html` or `home.miki`, and render the `card` partial.
+	- If your project places templates under `packages/product/templates/detail.html`, `render('detail', ..., { views: './views' })` will find it automatically.
+
+This behavior is opt‑out by simply clearing the app-dir names: `setAppTemplateDirNames([])` will disable app-style discovery.
+
 For API‑level details (e.g., `compile().renderPartial`) check `docs/api.md`.
 
 ---

package/ex.mjs

@@ -10,6 +10,8 @@ const dir=path.join(process.cwd(),"dir")
   // app.set('views', dir);
   miki.setupExpress(app, { extension: 'html', views: dir });
 
+
+  
   // registerContextProcessor((cx)=>({
   //   siteName:"code with miki",
   //   login:{'name':"miki", 'email':"miki@example.com"}
@@ -24,10 +26,11 @@ const dir=path.join(process.cwd(),"dir")
       {name:"miki", email:"jack@miki.com",address:"kumba"},
       {name:"luis",email:"luis@miki.com",address:"kumba"}
     ]
-    res.render("index",{name:"miki-template context", users:users, data:data})
+    res.render("index#card",{name:"miki-template context", users:users, data:data})
     // res.send(content)
   })
 
+
 app.listen(3000, () => {
     console.log('Server is running on port 3000 click: http://localhost:3000')
 }  )