Runes Cheat Sheet: Simplify $state and $derived with Decision Trees

[newsve]

Intro

There are actually multiple options of how to use $state and $derived with different implications. Following decision trees help narrowing down when to use which option. There is a summary at the bottom with default recommendations when starting out.

Its tl;dr is:

When starting out...

• ...default to $state objects (called Deep State in the docs) for state, e.g., $state({ value: 0 }) or $state([0, 0]) or $state([{ value: 0 }])
• ...default to functions (instead of $derived) for derived state, e.g., () => someState
• ...understand that other options have their place too, so read the following to get a better understanding

If you don't understand the terms in the decision trees you can find examples below the trees.

There are even more options than described but I limited the trees to those options you are going to use IRL and where high flexibility, less boilerplate and overall DX are key.

$state

graph TD;
  a(Does $state needs to be exported* or to be an object/array or to have methods?) -->|No| 1(__Option 1:__ $state primitive);
  a  -->|Yes| b;

  b(You don't need detailed type hints or does your state needs an embedded $derived as prop or do you need multiple instances?)-->|No| 2(__Option 2:__ $state object);
  b -->|Yes| 3(__Option 3:__ class with Rune fields);

Loading

Examples and docs for each option:

1. $state primitive: $state(0) docs
2. $state object (called Deep State in the docs): $state({ value: 0 }) docs
3. class with Rune fields: class Something { value = $state(0); d = $derived(this.value) } docs

You get most features with class and the ability to create multiple instances but it has the most boilerplate and the most minimal type hints, actually none except the class name; $state primitive is pretty bare bone and needs to be refactored if you want more but it's lean and a $state object is somewhere in the middle with very slight performance overhead but gives you way better type hints than a class.

You can still use $state objects when needing $derived, you just embed a function instead. Putting a $derived outside as a dedicated constant declaration doesn't always work because it can't be exported. So, with option 2 and you might rarely run into limitations and don't need to refactor while with option 1 things are much more limited. Option 2 seems to offer the most balanced package regarding features, flexibility, performance and DX.

Bonus tip: Always use arrow functions within classes, so this refers to the lexical scope or where the function was defined.

Here the same info as a comparison chart:

	$state primitive	$state object	Class with Rune fields
Can be exported?	-	y	y
Can be an object or array?	-	y	y
Can have methods?	-	y	y
Zero boilerplate?	9/10	6.5/10	5/10
Can have $derived props/fields?	-	-	y
Can have functions as derived state as props/fields instead?	-	y	y
Can create instances?	-	-	y
Full type hints?	y	y	-
No performance overhead (untested)?	y	-	y
Svelte 4 Stores can be embedded as props/fields	-	-	y

*This is actually "State needs write access and to be exported" but since $state always needs some write access at some point (otherwise why would I use $state?) it is shortened to "State needs to be exported".

$derived/$derived.by

graph TD;
  a(Does $derived needs to be exported?) -->|No| 1(__Option 1:__ $derived as constant);
  a  -->|Yes| b;

  b -->|No| 2(__Option 2:__ use a function instead);
  b(Do you want to embed $derived into a class with Runes?)-->|Yes| 3(__Option 3:__ $derived as class field);

Loading

Examples:

1. const someDerivedState = $derived(someState)
2. export const someDerivedState = () => someState or export const objectState = { someDerivedState: () => someState }
3. class ClassWRunes { someDerivedState = $derived(someState) }; export const classWRunes = new ClassWithRunes()

Once you want to export a $derived you need to embed it into a class with Runes which again has the most boilerplate and no type hints. It is easier to just use a function which can be embedded into $state object or just left outside and still be exported, in contrast to $derived.

Summary

While Runes give quite some options how to work with them it can be overwhelming when you just get started. All options have their place but to reduce complexity and mental overhead, you should have one default option in your mind and deviate when appropriate:

• $state objects (Deep State in the docs) give you much higher flexibility than $state primitives, still less boilerplate-y than classes and excellent type hints in contrast to classes
• $derived can't be exported, can't be embedded in $state objects, so while terse it is quite limited, functions are better in these regards
• Thus, I would default to $state objects and functions instead of $derived when starting out; with these option there are actually no limitations except the lack of instance creation which again can be compensated with arrays; once more familiar with Runes you realize that you use $state primitives and $derived as terser and/or more expressive API more in components; but be aware that once you want to export them you face some significant refactoring effort; classes might have slightly better performance (untested), can have instances and embed $derived and hence, save the calling brackets () when accessing the value in contrast to a function but again have zero type hints which makes consuming them cumbersome

[dgunning]

Finding Competitors/Peers Using SIC Codes

EdgarTools has a built-in solution for finding competitors/peers! Companies are classified by SIC (Standard Industrial Classification) codes, which group companies by industry.

Quick Example

from edgar import Company
from edgar.reference import get_company_dataset
import pyarrow.compute as pc

# Get your company's SIC code
company = Company("AAPL")  # Apple
sic = company.sic
print(f"Apple SIC: {sic}")  # 3571 - Electronic Computers

# Load company dataset (builds on first use, ~30 seconds)
companies = get_company_dataset()

# Find competitors with same SIC code
competitors = companies.filter(pc.field('sic') == sic)
print(f"Found {len(competitors)} companies in the same industry")

# View the results
import pandas as pd
df = competitors.to_pandas()
print(df[['name', 'tickers', 'sic_description']].head(10))

Output Example

Apple SIC: 3571
Found 47 companies in the same industry

                              name tickers                sic_description
0                    APPLE INC.      AAPL     Electronic Computers
1          INTERNATIONAL BUSINESS   IBM      Electronic Computers
2                   DELL INC.       DELL     Electronic Computers
3               HEWLETT-PACKARD    HPQ      Electronic Computers
...

Advanced: Find Similar Companies by SIC Range

SIC codes are hierarchical - the first 2 digits indicate broad industry:

# Find all computer & office equipment companies (SIC 357X)
tech_hardware = companies.filter(
    pc.field('sic').between(3570, 3579)
)
print(f"Found {len(tech_hardware)} tech hardware companies")

Performance

• First time: ~30 seconds to build dataset from SEC submissions
• Subsequent calls: <100ms (cached)
• Dataset size: ~562,413 companies

Common SIC Code Ranges

SIC Range	Industry
2834-2836	Pharmaceutical Preparations
3570-3579	Computer & Office Equipment
6021-6099	Banking
7370-7379	Computer Programming & Software
2800-2899	Chemicals & Allied Products

Finding Specific Competitors

If you want to find the top competitors by a specific metric (like market cap), you can:

1. Filter by SIC code (industry peers)
2. Add additional filters (exchange, state, etc.)
3. Fetch financials for comparison

# Get pharmaceutical competitors
pharma = companies.filter(pc.field('sic').between(2834, 2836))

# Filter to Nasdaq-listed only
nasdaq_pharma = pharma.filter(
    pc.field('exchanges').contains('Nasdaq')
)

# Get tickers
tickers_df = nasdaq_pharma.to_pandas()
competitor_tickers = [
    ticker for tickers in tickers_df['tickers'].dropna()
    for ticker in tickers.split('|')
]
print(f"Competitor tickers: {competitor_tickers}")

Bonus: Get All Filings from Competitors

Once you have competitor tickers, you can fetch their filings:

# Get competitor tickers
competitor_tickers = ['IBM', 'DELL', 'HPQ']

# Fetch recent filings from all competitors
for ticker in competitor_tickers:
    company = Company(ticker)
    recent_filings = company.get_filings(form='10-K').latest(1)
    print(f"{ticker}: {recent_filings}")

First-Time Setup

If you haven't used the dataset before:

# Download SEC submissions data (one-time, ~500 MB)
from edgar.storage import download_submissions
download_submissions()

# Then use get_company_dataset() - it will build automatically

---

Summary: Use get_company_dataset() + filter by sic field to find companies in the same industry. SIC codes provide industry classification from the SEC itself, making this the most authoritative way to identify competitors/peers without relying on external APIs or web scraping.