# Foam Core

`foam-core` is a (future) package that powers the core functionality in Foam across all platforms:

- VS Code Extension
- [[workspace-janitor]]
- [[cli]]
- Future initiatives
  - Visualizations
    - Tag clouds
    - Graph
    - Should we have a package for visualisation?
      - [[build-vs-assemble]]
      - Not everything needs to live in the Foam repo
  - Web based UI (Monaco)

`foam-core`'s primary responsibility is to build an API on top of a workspace of markdown files, which allows us to:

- Treat files as a graph, based on links
  - Can be either [[wiki-links]] or relative `[markdown](links.md)` style
  - We need to know about the edges (connections) as well as nodes
    - What link points to what other file, etc.
    - Needs to have the exact link text, e.g. even if `[[some-page]]` or `[[some-page.md]]` or `[[Some Page]]` point to the same document (`./some-page.md`), we need to know which format was used, so [[link-reference-definitions]] can be generated correctly
- Treat each file as semi-structured data
  - Title, headings, lists, paragraphs, images, links, data, code
  - Also, possible Foam-specific meta stuff, like "backlinks" or "block references".
  - This can power advanced search features (e.g. showing entire context of paragraph in back links, find all documents)

Ideally, `foam-core` will be generic enough that in can be used by third parties to build their own tools that operate on markdown directories.

## Technical requirements

- The graph should be relatively inexpensive to compute (for running in CI, mobile etc)
  - If necessary, we can implement caching inside a dot folder, but ideally not
  - In memory cache already exist, can prime from disk if needed
- The graph should be mutable (or immutable but easy to deep clone) so that persistent processes (VS Code) can cheaply update it when
  - Document content changes
    - Links update -> Graph change
    - Heading changes -> Metadata change
    - Anything in the document changes, update AST for individual note
  - Files are added
  - Files are removed
  - Files are renamed
  - Aliasing, call the same thing by multiple names
    - Doesn't exist yet, should we support?
- The graph should be observable (EventEmitter?) so changes can be applied
  - EventEmitter w/ cross platform dependency
  - Wonka (staltz's callbag)
  - Can be a long term goal
    - Short term fix: Just run the build fully on every change
- Ideally, the it should accept file/structure changes from the outside from some sort of event source, so we can decouple source of updates (VS Code Workspace events, file system events...)
  - If this gets complicated, we can delay this for now
- We should not take on platform-specific dependencies
  - Should work in any JS environment
- Written in TypeScript (preferably tsdx)
- Published to NPM

## Use cases

Here are some example use cases that the core should support. They don't need to be built into the core, but may help us design correct solutions:

- Adding and editing page content
  - [[materialized-backlinks]]
  - [[link-reference-definitions]] for [[wiki-links]]
  - [Frontmatter](https://jekyllrb.com/docs/front-matter/)
- Finding all documents with `#tag`
- Finding all documents with instances of `[[link]]`
- Visualisations
- Full text search

  - Or, if search is too expensive/complex, when given a list of file names and line/column positions from VS Code search API, can return the document context (e.g. full paragraph, preceding/following line etc)

## Collaboration

- This week
  - List of things to work in order
  - Provide more vision on future state
  - Write about working and collaboration philosophy
  - [[todo]] Prioritise roadmap
- Week of July 13
  - Jani is available full time to work on this
  - Janne: Write proposals, maybe more
  - Riccardo: Available

## Configuration management

- Other tools may not be able to use vscode
- [[todo]] Discuss with Janne and Riccardo

## Feature comparison

Useful for knowing what needs to be supported. See [[feature-comparison]].

## Meeting notes

- [[foam-core-2020-07-11]]

[//begin]: # "Autogenerated link references for markdown compatibility"
[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
[cli]: ../features/cli.md "Command Line Interface"
[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
[wiki-links]: ../wiki-links.md "Wiki Links"
[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
[todo]: todo.md "Todo"
[foam-core-2020-07-11]: ../meeting-notes/foam-core-2020-07-11.md "Foam Core 2020-07-11"
[//end]: # "Autogenerated link references"