DEV Community: artpani

Tuner is a flexible project configurator as code for Deno.

artpani — Sat, 21 Oct 2023 16:52:25 +0000

I think I’m not the only one who has a need to conveniently configure a project. And there are many ready-made solutions of varying degrees of complexity and freshness. In this topic I want to demonstrate a module for defining project settings and managing them as code. I’ve been using Deno not long ago, but a number of features about which many articles have already been written (comparison with Node.js and Bun) turned out to be very convenient, but the Deno community is not yet sufficiently developed and there are also few modules available.

Beginning of work

Let's create a /config directory in the project root. All the work with the configuration and its processing will be done here. The Tuner will automatically locate a folder with this specific name and gather the config object from there. The configuration file itself should end with .tuner.ts.

// config/myConfig.tuner.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export default Tuner.tune(
  {
    config: {
      field1: 'value1',
      field2: 100,
      field3: true,
      field4: ['minimalistic', 'convenient', 'dont you think?'],
    },
  },
);

Inside the tune function, the static analyzer will helpfully guide you that the configuration consists of two fields: env and config. In the file whose path is specified in deno.json, you can create a config object, and you can associate it with an alias like $global, for example:

// main.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export const tuner = await Tuner.use.loadConfig();
console.log(tuner.config.field2); // 100

After that, you can import {tuner} from "$global" in any file of the project and use it.

Upon execution, it is mandatory to have the env variable config, its value being the name of the config file without .tuner.ts extension. In this example, it is myConfig.

config=myConfig deno run --allow-all main.ts

In fact, this is the only required env variable that needs to be passed into the project (or set different values for the config variable in Doppler, if you use it).

Tuning secrets

In Tuner, you have the option to describe the types of environment variables and specify their behavior in case they are absent:

Default value
Process termination
Exception generation
Computation on-the-fly Here is a complete list of behaviors with different expected data types:

// config/myConfig.tuner.ts
import Tuner from 'https://deno.land/x/tuner/mod.ts';
export default Tuner.tune(
  {
    env: {
      // Use Default Value
      env1: Tuner.Env.getString.orDefault('default value1'),
      env2: Tuner.Env.getNumber.orDefault(100),
      env3: Tuner.Env.getBoolean.orDefault(true),
      // Ignore Absence of Variable
      env4: Tuner.Env.getString.orNothing(),
      env5: Tuner.Env.getNumber.orNothing(),
      env6: Tuner.Env.getBoolean.orNothing(),
      // Terminate Process
      env7: Tuner.Env.getString.orExit(
        'error message, optional',
      ),
      env8: Tuner.Env.getNumber.orExit(
        'will be printed to console before exit',
      ),
      env9: Tuner.Env.getBoolean.orExit(),
      // Generate Exception
      env10: Tuner.Env.getString.orThrow(new Error('error')),
      env11: Tuner.Env.getNumber.orThrow(new Error()),
      env12: Tuner.Env.getBoolean.orThrow(new Error()),
      // Compute Data Based on Provided Callback
      // (can be asynchronous, if data needs to be fetched from disk or remotely, for example)
      env13: Tuner.Env.getString.orCompute(() => 'computed value1'),
      env14: Tuner.Env.getNumber.orAsyncCompute(() =>
        new Promise(() => 100)
      ),
    },
    config: {
      field1: 'value1',
      field2: 100,
      field3: true,
      field4: ['minimalistic', 'convenient', 'isn\'t it?'],
    },
  },
);

Of course, you can simply specify a primitive value, for example, env1: 100.

We're building a hierarchy of configs

Sometimes a config consists of data that is not equally important and will need to be updated at different frequencies. To separate the 'core' data from the 'secondary', I recommend splitting the config into several mini-configs, creating a kind of hierarchy from them.

Tuner allows you to 'assemble' a config using other configs, you just need to build a chain:

The current config will be supplemented with all the fields of the parent, while retaining its values.
The current config will be supplemented with all the fields of the child, with matching fields being overwritten by values from the child config.

Function values used to describe env variables also follow these rules.

Let's see how to do this in the code:

// config/develop.tuner.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export default Tuner.tune({
  child: Tuner.Load.local.configDir('a.tuner.ts'),
  parent: Tuner.Load.local.configDir('base.tuner.ts'),
  config: {
    a: 300,
    b: 301,
  },
});


//config/base.tuner.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export default Tuner.tune({
  config: { a: 400, b: 401, c: 402 },
});


//config/a.tuner.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export default Tuner.tune({
child: Tuner.Load.local.configDir('b.tuner.ts'),
  config: {
    b: 200,
    e: 201,
  },
});


//config/b.tuner.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export default Tuner.tune({
  config: { a: 100, d: 101 },
});


//main.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
export const tuner = await Tuner.use.loadConfig();
console.log(tuner);
//{ config: { a: 100, b: 200, c: 402, e: 201, d: 101 }, env: {} }

Tuner.Load provides several options for defining the source of the config. You can connect them locally, import them remotely, or request them through a provided callback

Tuner.Load offers both local and remote ways to connect a config.

Tuner.Load.local

Function	Returns the config object from the file by...
absolutePath(path:string)	...specifying the full path to it.
configDir(path:string)	...specifying the path relative to the directory named "config".
cwd(path:string)	...specifying the path relative to the project directory.

Tuner.Load.remote

Function	Description	Example (assuming the config file is located at http://some_server/b.tuner.ts)
import(path:string)	Works like a regular import.	child: Tuner.Load.remote.import(”http://some_server/b.tuner.ts”)
callbackReturnModule(cb: () ⇒ Promise<{default: ITunerConfig}>)	Accepts a callback that returns a promise with the imported module.	child: Tuner.Load.remote.callbackReturnModule(() ⇒ import(”http://some_server/b.tuner.ts”))
callbackReturnString((cb: () => Promise))	Accepts a callback that returns a promise with the module's code as a string (retrieve the config code from forms, blocks in Notion, etc.)	child: Tuner.Load.remote.callbackReturnString(() ⇒ someFetchingFunctionStringReturned(options: {…}))

Additionally, Tuner.Load.remote comes with built-in integrations with various services through Tuner.Load.remote.providers:

notion(key:string, blockUrl:string) - provide the authorization key (use Tuner.getEnv to find the env variable in the environment or .env file) and the link to the block in Notion where the configuration module is described.

github(key: string, owner: string, repo: string, filePath: string) - key, repository owner's username, repository name, and file path. Some may find the idea of configuring a project through Notion strange... I understand that. But it was more convenient for my project, so this integration is available. If you have any suggestions, feel free to let me know, adding them is not difficult :)

And the cherry on top - the config schema.

Working with the config would be unpleasant without a schema and displayed types.

For convenient development with the config object, it is recommended to generate a type for the object.

Tuner.use.generateSchema(obj: ObjectType, variableName: string, filePath: string) will create a file at the filePath with the schema of the obj object and export a type with the name variableName, capitalizing the first letter.

You can separate the schema generation process into a separate task, so that, for example, deno task schema would be responsible solely for updating the schema.

Example:

const tuner = await Tuner.use.loadConfig();
Tuner.use.generateSchema(
  tuner,
  'config',
  'config/configSchema.ts',
);

We will see:

//config/configSchema.ts
import { z } from '<https://deno.land/x/zod/mod.ts>';
export const configSchema = z.object({
config: z.object({
a: z.number(),
b: z.number(),
c: z.number(),
e: z.number(),
d: z.number(),
}),
env: z.object({}),
});
export type Config = z.infer<typeof configSchema>;
//├─ config
//│  ├─ a
//│  ├─ b
//│  ├─ c
//│  ├─ e
//│  └─ d
//└─ env

Now we can complement the code snippet with the initialization of the config type for Tuner, and we will have a powerful and informative way to interact with our config:

// main.ts
import Tuner from '<https://deno.land/x/tuner/mod.ts>';
import {Config} from "config/configSchema.ts"
export const tuner = (await Tuner.use.loadConfig()) as Config;

Conclusion

Of course, this is just an example of how to organize working with relatively constant configuration data. There is room for growth and expansion.

A feature is already prepared in the form of a change observer (if a field in one of the configs is changed, an event or callback is triggered). However, in this version of Tuner (which I haven't released yet), there is a memory leak. Once I fix it, I'll release it to the Deno community. I would be grateful for any observations, constructive criticism, recommendations, and suggestions.

Как сделать TG Instant View из страницы Notion

artpani — Mon, 18 Sep 2023 08:56:59 +0000

Как верстать в Notion

Чтобы все отображалось и работало, верстать страницу в Notion нужно придерживаясь следующих правил:

Заголовок страницы станет заголовком Instant View(далее - IV).
Все изображения должны быть вставлены через /embed, обычная вставка прикрутит картинке URL amazonaws таким образом, что IV Bot телеграмма не сможет зафетчить ее.
Если какие-то абзацы нужно будет отобразить как Blockquote, в Notion нужно сделать этот блок типом Quote.

Как Blockquote выглядит в IV

Как этот же блок верстался в Notion

Вообще делать большие статьи в IV вряд ли получится и навешивать много сложных блоков в статью тоже не стоит, чем проще - тем лучше.

Как настроить шаблон IV

Идем в My Templates и вставляем в поле ссылку на статью и жмем Enter

Чтобы получить ссылку на страницу в Notion, нужно выбрать Share в правом верхнем углу экрана и сменить тумблер Share to web

В появившимся окне по центру нужно прописать правила, по которым IV Bot будет парсить структуру страницы. Минимально рабочий шаблон такой:

~version: "2.1"
body: //body
title: "@head//title"
@replace_tag(<figure>): $body//p[.//img]
# <aside> ://p[contains(text(), '<aside>')]
author: "eclipse_it"

“~version” - без указания версии рендер крашится

“body: //body” - тут указывается самый узкий в плане вложенности блок с полезным контентом. При создании шаблона IV для обычного блога достаточно указать какой-нибудь article, если имеется такой тег:

body: //article

или div с id=”content”:

body: //div[@id="cover"]

или div с классом “content-page”, например:

body: //div[has-class("content-page")]

“title: @head//title” - Заголовок будет помещен в теге <title>, ловим его оттуда

“@replace_tag(<figure>): $body//p[.//img]” - ~~не спрашивайте~~ Да, Notion помещает тег <img> внутрь <p>, парсер на этом ломается

“author: "eclipse_it"" - название канала или имя автора

“# <aside> ://p[contains(text(), '<aside>')]” - тут можно строку удалить, я пока не особо понял, как решить эту проблему. Дело в том, что блок Callout из Notion

В HTML-коде выглядит вот так

Поэтому необходимо как-то преобразовать данный <p>

Как прикрутить IV к посту

После того, как макет настроен, надо нажать Track Changes в правом верхнем углу, после чего Mark as checked.

Чтобы получить линк —> View in Telegram

Полученную ссылку нужно вставить в пост, но чтобы не засорять ссылкой текст, можно воспользоваться невидимым символом “ㅤ” (имеет код “U+3164”, “&#12644”), на который вешаем ссылку.

How to create TG Instant View from Notion page

artpani — Mon, 18 Sep 2023 08:46:57 +0000

Title image is MidJourney generated (Notion blended with Instant View TG)

How to format in Notion

To ensure everything displays and works correctly, formatting a page in Notion needs to follow these rules:

The page title will become the Instant View (IV) title.
All images must be inserted through /embed. Ordinary insertions will attach the image's URL to amazonaws in such a way that the IV Bot of Telegram cannot fetch it.
If some paragraphs need to be displayed as Blockquote, in Notion, this block should be made as a Quote type.

How Blockquote looks in IV

How the same block was formatted in Notion

In general, it is unlikely to be able to make large articles in IV, and it is also not worth adding many complex blocks to the article. The simpler - the better.

How to customize the IV template

Go to My Templates and insert the article's link into the field and press Enter.

To get the link to the page in Notion, select Share in the upper right corner of the screen and switch the Share to web toggle.

In the window that appears in the center, you need to specify the rules by which the IV Bot will parse the page structure. The minimally working template is as follows:

~version: "2.1"
body: //body
title: "@head//title"
@replace_tag(<figure>): $body//p[.//img]
# <aside> ://p[contains(text(), '<aside>')]
author: "eclipse_it"

“~version” - without specifying a version, the render crashes.

“body: //body” - here, the narrowest block in terms of nesting with useful content is specified. When creating an IV template for a regular blog, it is enough to specify any article if such a tag exists:

body: //article

or div with id="content":

body: //div[@id="cover"]

or div with class "content-page," for example:

body: //div[has-class("content-page")]

“title: @head//title” - The title will be placed in the

tag, catch it from there.

“@replace_tag(<figure>): $body//p[.//img]” - ~~don't ask~~ Yes, Notion places the <img> tag inside <p>, and the parser crashes on it.

“author: "eclipse_it""- channel name or author's name.

“# <aside> ://p[contains(text(), '<aside>')]” - here, the line can be removed. I have not yet fully understood how to solve this problem. The thing is that the Callout block from Notion:

In HTML code, it looks like this:

Therefore, it is necessary to somehow transform this <p>.

How to attach IV to a post

After the layout is configured, you need to click Track Changes in the upper right corner, then Mark as checked.

To get the link -> View in Telegram

The obtained link needs to be inserted into the post, but to avoid cluttering the text with a link, you can use the invisible character "ㅤ" (code "U+3164", "&#12644"), on which a link is hung.